|
DataMuseum.dkPresents historical artifacts from the history of: DKUUG/EUUG Conference tapes |
This is an automatic "excavation" of a thematic subset of
See our Wiki for more about DKUUG/EUUG Conference tapes Excavated with: AutoArchaeologist - Free & Open Source Software. |
top - metrics - downloadIndex: T l
Length: 52302 (0xcc4e)
Types: TextFile
Names: »lispref-2«
└─⟦a05ed705a⟧ Bits:30007078 DKUUG GNU 2/12/89
└─⟦c06c473ab⟧ »./UNRELEASED/lispref.tar.Z«
└─⟦1b57a2ffe⟧
└─⟦this⟧ »lispref-2«
Info file: lispref, -*-Text-*-
produced by texinfo-format-buffer
from file: lispref.texinfo
This file documents GNU Emacs Lisp.
This is Edition 0.1 Beta of the GNU Emacs Lisp Reference Manual, for
Emacs Version 18, with some references to Emacs Version 19.
Please read this document for review purposes.
Published by the Free Software Foundation, 675 Massachusetts Avenue,
Cambridge, MA 02139 USA
Copyright (C) 1989 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Foundation.
▶1f◀
File: lispref Node: Association List Type, Prev: Dotted Pair Notation, Up: List Type
Association List Type
.....................
An "association list" or "alist" is a specially constructed list of
cons cells. In each cons cell, the CAR is treated as a "key", and the
CDR is treated as an associated "value". Association lists are often
used to record information that one might otherwise keep on a stack,
since new pairs may be simply added to the front of the list.
Elements of an alist may be written using either dotted pair notation or
regular notation, but in any single application, you must use one
notation consistently. In Emacs, dotted pair notation is most often
used for alists.
For example,
(setq alist-of-colors '((rose . red) (lilly . white) (buttercup . yellow)))
sets the variable `alist-of-colors' to an alist of three elements. In
the first element, `rose' is the key and `red' is the value.
*Note Association Lists::, for a further explanation of alists and for
functions that work on alists.
▶1f◀
File: lispref Node: Array Type, Prev: List Type, Up: Programming Types, Next: String Type
Array Type
----------
An "array" object is composed of an arbitrary number of other Lisp
objects. Any element of an array may be accessed in constant time. In
contrast, an element of a list requires access time that is proportional
to the position of the element in the list. Elements at the end of a
list take longer to access that elements at the beginning of a list.
Emacs defines two types of array, both of which are one-dimensional: a
string and a vector. A string is an array of characters and a vector is
an array of arbitrary objects. (In other programming languages, the
term ``array'' has a more general meaning than it does in Emacs Lisp.)
Each type of array has its own read syntax (*Note String Type::, and
*Note Vector Type::).
* Arrays may have any length, up to the size of the largest integer;
but once created, an array has a fixed size.
* Arrays are indexed such that the first element of an array has an
index of zero, the second element as an index of 1, and so on.
This is called "zero-origin" indexing. For example, an array of
four elements is indexed by 0, 1, 2, and 3.
* The elements of any array may be referenced or changed with the
functions `aref' and `aset', respectively (*Note Arrays::).
The array type is a subtype of sequences and a supertype of strings
and vectors.
▶1f◀
File: lispref Node: String Type, Prev: Array Type, Up: Programming Types, Next: Vector Type
String Type
-----------
A "string" is an array of characters. Strings are used for many
purposes, as can be expected in a text editor. Examples of strings
include the names of Lisp symbols, messages for the user, and substrings
extracted from buffers.
The read syntax for strings is a double-quote, an arbitrary number of
characters, and another double quote, `"like this"'. The Lisp reader
will accept 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). This means that you enter a double-quote
in a string by preceding it with a backlslash, and you enter a character
`A', `C-a', or a `M-C-A' the same way: `"like this: \", \A, \C-a,
\M-\C-a"'. (*Note Character Type::, for a description of the read
syntax for characters.)
Unlike the C programming language, newlines are allowed in Emacs Lisp
string literals. But an escaped newline---one that is preceded by
`\'---does not become part of the string; i.e., the Lisp reader ignores
an escaped newline in a string literal.
"It is useful to include newlines in
documentation strings, but the newline is \
ignored if escaped."
=> "It is useful to include newlines in
documentation strings, but the newline is ignored if escaped."
The print representation of strings is a double-quote, the characters
in it, and another double-quote with the exception that any backslash or
double-quote characters in the string are printed with a leading
backslash `"like this \" embedded quote"'.
*Note Strings and Characters::, for functions that work with strings.
▶1f◀
File: lispref Node: Vector Type, Prev: String Type, Up: Programming Types, Next: Symbol Type
Vector Type
-----------
A "vector" object is a one-dimensional array of elements each of which
can be of any type. It takes a constant amount of time to access any
element of a vector. On the other hand, in a list, the access time of
an element is proportional to the distance of the element from the
beginning of the list.
The print representation and read syntax of vectors are the same: a
left square bracket, elements, and a right square bracket. Like numbers
and strings, vectors return themselves when evaluated.
[1 "two" (three)] ; A vector of three elements.
=> [1 "two" (three)]
*Note Vectors::, for functions that work with vectors.
▶1f◀
File: lispref Node: Symbol Type, Prev: Vector Type, Up: Programming Types, Next: Lisp Function Type
Symbol Type
-----------
A "symbol" in GNU Emacs Lisp is an object that serves several
purposes. A symbol may be used in programs to refer to a global
variable value, a function, a property list, or the symbol itself. In a
given context, usually only one of these uses is intended.
To support these uses, symbols have four attributes or "cells":
* a print name cell
* a function cell
* a value cell
* a property list cell.
You may imagine a symbol as being a chest of four drawers. The
function definition is put in one drawer, the value in another, and so
on. Each drawer, or cell, is a reference to some other Lisp object What
is put in the drawer holding the value can be changed without affecting
the contents of the drawer holding the function definition, and
vice-versa. Note that the print name is *not* the symbol; the print
name has a drawer of its own. The print name is a way of mentioning the
symbol; the symbol is the whole chest of drawers.
In any symbol, either the function cell or the value cell or both of
them may be empty or "void". (The term "void" is used to indicate that
a cell has no valid data in it, as in the error message, `The symbol's
value is void'. This should not be confused with the symbol whose name
is `void'. Note also that the data in a cell may be `nil', which is not
void either.)
The four functions, `symbol-name', `symbol-value', `symbol-plist', and
`symbol-function', return the contents of the four cells.
An example is the symbol `buffer-file-name', which has the print name
`buffer-file-name' and data in the value, function, and property list
cells.
(symbol-name 'buffer-file-name)
=> "buffer-file-name"
(symbol-value 'buffer-file-name)
=> "/gnu/elisp/objects.texinfo"
(symbol-plist 'buffer-file-name)
=> (variable-documentation 29529)
(symbol-function 'buffer-file-name)
=> #<subr buffer-file-name>
The value cell of the symbol contains the name of this file. The
propertly list cell contains the list `(variable-documentation 29529)'
which tells the Emacs help and documentation functions where to find
documentation about `buffer-file-name' in the `DOC' file. (29529 is the
offset from the beginning of the `DOC' file where the documentation for
the function begins.) The function cell contains the code for returning
the name of the file. Since `buffer-file-name' is a primitive function,
its code has no read syntax and prints in hash notation. (*Note
Primitive Function Type::. (A function definition written in Lisp will
have the Lisp (or the byte-code) in this cell.)
The Print Name Cell
...................
The "print name" is the most obvious characteristic of a symbol, and
is described in this section. The other cells of symbols are described
in greater detail in *Note Symbols::.
You often use the print name of a symbol to refer to it; the print
name is what the printer prints when handed a symbol. The print name is
what distinguishes one symbol from another when the Lisp reader reads
them. The print name cell is always a string object.
You use a symbol in a program by typing its print name (without the
double-quotes that delimit strings). The rules for reading the print
name of a symbol are similar to those for reading a string. Any of the
characters `A-Z', `a-z', `0-9', and `-+*/_~!@$%^&=:<>{}' are read as
part of a symbol's name. 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 print name of a symbol does no more
than quote the single character that follows the backslash, without
conversion. For example, in a string, `\t' represents a TAB; in the
print name of a symbol, however, `\t' merely quotes the letter `t'. To
have a symbol with a tab character in its name, you must actually type
an (escaped) tab. But you would hardly ever do such a thing.
Common Lisp Note: In Common Lisp, lower case letters are always
``folded'' to upper case, unless they are explicitly escaped. This
is a marked contrast to Emacs Lisp, in which uppercase and
lowercase letters are distinct.
Here are several examples of symbol names. Note that the `+' in the
last example is read as a symbol name instead of a number, because it is
not followed only by digits.
foo ; A symbol named `foo'.
FOO ; A symbol named `FOO', different from `foo'.
char-to-string ; A symbol named `char-to-string'.
1+ ; A symbol named `1+'
; (not `+1', which is an integer).
\+1 ; A symbol named `+1' (not a very readable name).
\(*\ 1\ 2\) ; A symbol named `(* 1 2)' (a worse name).
+-*/_~!@$%^&=:<>{} ; A symbol named `+-*/_~!@$%^&=:<>{}'.
; These characters need not be escaped.
▶1f◀
File: lispref Node: Lisp Function Type, Prev: Symbol Type, Up: Programming Types, Next: Lisp Macro Type
Lisp Function Type
------------------
Just as functions in other programming languages are executable, a
"Lisp function" object is a piece of executable code. However, Lisp
functions may also be considered data, unlike the functions in many
other languages; this is because a Lisp function object is a list whose
first element is the symbol `lambda' (*Note Lambda Expressions::); or,
in some cases, a Lisp function object is a "subr" written in the C
programming language (*Note Primitive Function Type::).
A "named function" is a symbol with something in its function cell.
You define a named function with the special form `defun'. For example,
(defun foo (n)
(print n))
=> foo
(symbol-function 'foo)
=> (lambda (n) (print n)) ; An interpreted function.
An "anonymous Lisp function", on the other hand, may be created by
building a list that begins with `lambda'.
Each of the following forms returns a value of 3. The `funcall'
function calls its first argument, passing the remaining arguments to
it. In the first example, the function that `funcall' calls is `+'. In
the second example, the function object is the list starting with
`lambda'. (In the second example, the list starting with `lambda'
accomplishes exactly the same as `+' does in the first example; however,
you may write the anonymous function as complexly as you like.) In the
third example, the anonymous function is quoted with `function' instead
of with `quote' (for which `'' is the short form).
(funcall '+ 1 2)
=> 3
(funcall '(lambda (arg1 arg2) (+ arg1 arg2)) 1 2)
=> 3
(funcall (function (lambda (arg1 arg2) (+ arg1 arg2))) 1 2)
=> 3
Anonymous functions are often used in circumstances where the program
itself writes the function. In this case, the exact definition of the
list starting with `lambda' is not known until the anonymous function is
called.
Incidently, if you know ahead of time that a list is going to be an
anonymous function, and you need to apply the `quote' function to it, it
is best to quote it with the special form `function' rather than with
`quote'. This is because the `function' special form tells the byte
compiler to compile the list as a function. The `function' special form
is equivalent to `quote' for interpreted code. (*Note Anonymous
Functions::.)
*Note Functions::, for explanations of `lambda', `defun', and
functions that work with functions.
▶1f◀
File: lispref Node: Lisp Macro Type, Prev: Lisp Function Type, Up: Programming Types, Next: Primitive Function Type
Lisp Macro Type
---------------
A "Lisp macro" object is a piece of executable code, like a function,
but with different parameter-passing semantics. A Lisp macro is a list
whose first element is the symbol `macro' and the remainder is the same
as a Lisp function object, including the `lambda' symbol.
Lisp macro objects are usually defined with the built-in function
`defmacro'. Any list that begins with `macro', however, is a macro as
far as Emacs is concerned. *Note Macros::, for an explanation of how to
write a macro.
▶1f◀
File: lispref Node: Primitive Function Type, Prev: Lisp Macro Type, Up: Programming Types, Next: Autoload Type
Primitive Function Type
-----------------------
A "primitive function" is a function callable from Lisp but written in
the C programming language. Primitive functions are also called "subrs"
(subroutines) or "built-in functions". Most primitive functions
evaluate all their arguments when they are called. A primitive function
that does not evaluate all its arguments is called a "special form"
(*Note Special Forms::).
To the caller of a function, it does not matter if the function is
primitive. However, it 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. So
long as the redefined function is called from Lisp, the new definition
will be used; but a call from C code may still use the old definition.
The term "function" is used to refer to all Emacs functions, whether
written in Lisp or C. *Note Lisp Function Type::, for information about
the functions written in Lisp.
Primitive functions have no read syntax and print in hash notation
with the name of the subroutine.
(symbol-function 'car) ; Access the function cell of the symbol.
=> #<subr car>
(subrp (symbol-function 'car)) ; Is this a subroutine?
=> t ; Yes.
▶1f◀
File: lispref Node: Autoload Type, Prev: Primitive Function Type, Up: Programming Types
Autoload Type
-------------
An "autoload" object is a list whose first element is the symbol
`autoload'. An autoload object is usually created with the function
`autoload', which stores the object in the function cell of a symbol.
An autoload object references a file to load when the symbol is used as
a function. After the file has been loaded, the symbol should have a
new function cell that is not an autoload object. The contents of this
cell are evaluated as if they had been there originally. This means
that from the point of view of a user, the function call works as
expected, using the function definition in the loaded file.
*Note Autoload::, for a longer explanation.
▶1f◀
File: lispref Node: Editing Types, Prev: Programming Types, Up: Types of Lisp Object, Next: Type Predicates
Editing Types
=============
The types in the previous section are common to many Lisp-like
languages. But Emacs Lisp is more than an ordinary Lisp: many
additional data types and functions are provided for dealing with
editing in addition to Lisp programming per se.
* 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.
▶1f◀
File: lispref Node: Buffer Type, Prev: Editing Types, Up: Editing Types, Next: Window Type
Buffer Type
-----------
A "buffer" object contains an indefinite number of characters. A
buffer is most commonly used to hold the contents of a disk file (*Note
Files::). Most buffers are also meant to be seen by the user, and
therefore displayed, at some time, in a window (*Note Windows::). But a
buffer need not have an associated file or window.
Buffers can be thought of as simple string, albeit often very long,
but they are, in fact, more complex. For example, text can be inserted
into a buffer very quickly, while ``inserting'' text into a string is
accomplished with concatenation and the result is an entirely new string
object.
Each buffer has a designated position within the buffer, called the
"point" (*Note Positions::). Although many buffers may exist
simultaneously, only one buffer is the "current buffer". Most editing
commands act on the contents of the current buffer in the neighborhood
of its point. Many other functions manipulate or test the characters in
a buffer and, indeed, quite a bit of this manual is devoted to
describing such functions.
Several other data structures are associated with buffers:
* a local syntax table (*Note Syntax Tables::);
* a local keymap (*Note Keymaps::); and,
* a local variable binding list (*Note Variables::).
Each of these overrides its global counterpart. By paying attention to
the "buffer-local" object instead of its global counterpart, editing
commands are able to provide a different behavior in each buffer.
Buffers have no read syntax. They print in hash notation with the
buffer name.
(current-buffer)
=> #<buffer objects.texinfo>
*Note Buffers::, for details about buffer objects and buffer-related
functions and variables.
▶1f◀
File: lispref Node: Window Type, Prev: Buffer Type, Up: Editing Types, Next: Window Configuration Type
Window Type
-----------
A "window" object describes the portion of the terminal screen that
Emacs uses to display a buffer. Every window has an associated buffer,
but a buffer might not be displayed in any window. On the other hand, a
buffer may be displayed in more than one window.
While many windows may exist simultaneously, only one window is the
"selected window". This is the window where the cursor is (usually)
displayed when command input is requested. The selected window usually
displays the current buffer, but this is not necessarily the case. In
particular, when Emacs (rather than a human) works on a buffer, that
buffer is the current buffer, but it does not have to be visible to the
user. The `set-buffer' function is used to transfer Emacs's attention
without changing the displayed buffer. (*Note Changing Buffers::.)
Windows have no read syntax. They print in hash notation, giving the
window number and buffer name. (The window numbers are only to help
humans debug using the windows' printed representation.)
(selected-window)
=> #<window 1 on objects.texinfo>
*Note Windows::, for a description of the functions that work on
windows.
▶1f◀
File: lispref Node: Window Configuration Type, Prev: Window Type, Up: Editing Types, Next: Marker Type
Window Configuration Type
-------------------------
A "window configuration" object 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
`#<window-configuration>'. *Note Window Configurations::, for a
description of several functions related to window configurations.
▶1f◀
File: lispref Node: Marker Type, Prev: Window Configuration Type, Up: Editing Types, Next: Process Type
Marker Type
-----------
A "marker" object denotes a position in a specific buffer. Markers
therefore have two cells: 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
(unless the insertion or deletion is at the marker position).
Markers have no read syntax. They print in hash notation, giving the
current character position and the name of the buffer.
(point-marker)
=> #<marker at 10779 in objects.texinfo>
*Note Markers::, for information on how to test, create, copy, and move
markers.
▶1f◀
File: lispref Node: Process Type, Prev: Marker Type, Up: Editing Types, Next: Stream Type
Process Type
------------
A "process" object references a subprocess that runs independently of
the Emacs process. External subprocesses, such a shells, GDB, telnet,
and compilers, may be used to extend the processing capability of Emacs
far beyond the limitations of Emacs Lisp.
A process takes input from Emacs and the output is returned 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.
(process-list)
=> (#<process shell>)
*Note Processes::, for information about functions that create, delete,
return information about, send input or signals to, and receive output
from processes.
▶1f◀
File: lispref Node: Stream Type, Prev: Process Type, Up: Editing Types, Next: Keymap Type
Stream Type
-----------
A "stream" object is used as a source or sink for characters. A
stream is a Lisp object that can either supply characters or accept them
as output. Many different objects 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
`*Help*' buffer, or to the echo area.
The object `nil', in addition to its other meanings, stands for the
stream referenced by the variables `standard-input' and
`standard-output'. Also, the object `t' stands for input or output in
the minibuffer (*Note Minibuffers::).
Streams have no special print or read syntax; and print as whatever
object they are.
*Note Streams::, for a description of various functions related to
streams, including various parsing and printing functions.
▶1f◀
File: lispref Node: Keymap Type, Prev: Stream Type, Up: Editing Types, Next: Syntax Table Type
Keymap Type
-----------
A "keymap" object maps keys typed by the user to functions. Emacs
defines two kinds of keymaps: "full keymaps", which are vectors of 128
elements, and "sparse keymaps", which are association lists with a
preceding `keymap' symbol.
*Note Keymaps::, for information about creating keymaps, handling
prefix keys, local as well as global keymaps, and changing key bindings.
▶1f◀
File: lispref Node: Syntax Table Type, Prev: Keymap Type, Up: Editing Types
Syntax Table Type
-----------------
A "syntax table" object is a vector of 256 integers. Each element of
the vector defines how the corresponding character is interpreted when
it appears in a buffer. For example, in C mode (*Note Major Modes::),
the `+' 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 `+', i.e., for position 43.
Syntax tables are only used for scanning text in buffers, not for
reading Lisp expressions. The table which the Lisp interpreter uses to
read expressions is built into the Emacs source code and cannot be
changed. For example, you cannot change the list delimiters to be `{'
and `}' instead of `(' and `)'.
*Note Syntax Tables::, for details about syntax classes and how to
make and modify syntax tables.
▶1f◀
File: lispref Node: Type Predicates, Prev: Editing Types, Up: Types of Lisp Object, Next: Equality Predicates
Type Predicates
===============
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 objects in Lisp are not declared to be of a
certain type, as they are in other programming languages. It is
therefore up to each individual function to test whether each actual
argument belongs to a type that that produces a desired result when
passed to the function.
All built-in functions do check the types of their actual arguments when
appropriate and signal a `wrong-type-argument' error if an argument is
of the wrong type.
For example,
(+ 2 'a)
=> Wrong type argument: integer-or-marker-p, a
Many functions, called "type predicates", are provided to test whether
an object is a member of a given type. (Following a convention of long
standing, the print names of most Emacs Lisp predicates end in `p'.)
Here is a table pre-defined type predicates, in alphabetical order, and
where they are described further.
`atom'
*Note List-related Predicates::
`arrayp'
*Note Arrays::
`bufferp'
*Note Buffers::
`char-or-string-p'
*Note Predicates for Strings::
`consp'
*Note List-related Predicates::
`integer-or-marker-p'
*Note Predicates on Markers::
`integerp'
*Note Predicates on Numbers::
`keymapp'
*Note Creating Keymaps::
`listp'
*Note List-related Predicates::
`markerp'
*Note Predicates on Markers::
`natnump'
*Note Predicates on Numbers::
`nlistp'
*Note List-related Predicates::
`processp'
*Note Processes::
`sequencep'
*Note Sequence Functions::
`stringp'
*Note Predicates for Strings::
`subrp'
*Note Function Cells::
`symbolp'
*Note Symbols::
`syntax-table-p'
*Note Syntax Tables::
`user-variable-p'
*Note Global Variables::
`vectorp'
*Note Vectors::
`windowp'
*Note Window Basics::
▶1f◀
File: lispref Node: Equality Predicates, Prev: Type Predicates, Up: Types of Lisp Object
Equality Predicates
===================
Two functions test equality between any two objects. These are
described here. Other functions test equality between objects of
specific types, e.g., strings. See the appropriate chapter for these
predicates.
* Function: eq OBJECT1 OBJECT2
This function returns `t' if OBJECT1 and OBJECT2 are the same
object, `nil' otherwise. The ``same object'' means, in this case,
that a change in one will be reflected by the same change in the
other.
`eq' will be true if OBJECT1 and OBJECT2 are numbers with the
same value, or symbols with the same print name. Other objects
(e.g., lists, vectors, strings) with the same elements may or may
not be `eq' to each other.
(The `make-symbol' function returns an uninterned symbol that is
not interned in the standard `obarray'; such symbols should not be
tested against interned symbols until they are interned; *Note
Creating and Interning Symbols::.)
(eq 'foo 'foo)
=> t
(eq 456 456)
=> t
(eq "asdf" "asdf")
=> nil
(eq '(1 (2 (3))) '(1 (2 (3))))
=> nil
(eq [(1 2) 3] [(1 2) 3])
=> nil
(eq (point-marker) (point-marker))
=> nil
* Function: equal OBJECT1 OBJECT2
This function returns `t' if OBJECT1 and OBJECT2 have equal
components, `nil' otherwise. Whereas `eq' tests if two objects are
the same, `equal' looks inside the objects, if necessary, to see if
their elements are the same. So, if two objects are `eq', they are
`equal', but the converse is not always true.
(equal "asdf" "asdf")
=> t
(equal "asdf" "ASDF")
=> nil
(equal '(1 (2 (3))) '(1 (2 (3))))
=> t
The test for equality is implemented recursively, and circular lists may
therefore cause infinite recursion (leading to an error).
▶1f◀
File: lispref Node: Numbers, Prev: Types of Lisp Object, Up: Top, Next: Strings and Characters
Numbers
*******
Integers are the one kind of number in version 18 Emacs Lisp. These are
whole numbers such as -3, 0, 7, 13, and 511.
In version 19, there is a compile time option to support floating point
numbers, which are represented internally as the C type `double'. A
floating point number is a number with a fractional part, such as -4.5,
0.0, or 2.71828. A floating point number can be expressed in an
exponetial notation as well: thus, 1.5e2 equals 150; in this example,
`e2' stands for ten to the second power, and is multiplied by 1.5.
* Menu:
* Number Basics::
* Predicates on Numbers::
* Comparison of Numbers::
* Arithmetic Operations::
* Bitwise Operations on Integers::
* Random Numbers::
▶1f◀
File: lispref Node: Number Basics, Prev: Numbers, Up: Numbers, Next: Predicates on Numbers
Number Basics
=============
The range of values for a small integer depends on the machine. The
range is -8388608 to 8388607 (24 bits; i.e.,
-2**24 to
2**24 - 1 ) on most machines, but on others it is -16777216 to 16777215
(25 bits), or -33554432 to 33554431 (26 bits). All of the examples
shown below assume an integer has 24 bits.
The Lisp reader reads numbers as a sequence of digits with an optional
sign.
1 ; The integer 1.
+1 ; Also the integer 1.
-1 ; The integer -1.
16777217 ; Also the integer 1, due to overflow.
0 ; The number 0.
-0 ; The number 0.
1. ; Invalid syntax.
To understand how various functions work on integers, especially the
bitwise operators (*Note Bitwise Operations on Integers::), it is often
helpful to view the numbers in their binary form.
In 24 bit binary, the decimal integer 5 looks like this:
0000 0000 0000 0000 0000 0101
(In the example, a space is put every 4 bits, and two spaces every 8
bits, to make the binary integer easier to read.)
The negative integer, -1, looks like this:
1111 1111 1111 1111 1111 1111
-1 is represented as 24 ones. (In jargon, this is called `"two's
complement" notation.)
The negative integer, -5, is creating by subtracting 4 from -1. In
binary, the decimal integer 4 is 100. Consequently, -5 looks like this:
1111 1111 1111 1111 1111 1011
In this implementation, the largest 24 bit binary integer is the
decimal integer 8,388,607. In binary, this number looks like this:
0111 1111 1111 1111 1111 1111
This binary number consists of all 1's, except for the left-most digit,
which is zero.
As we said before, the arithmetic functions do not check whether
integers go outside their range; hence, when you add 1 to 8,388,607, the
negative integer -8,388,608 is returned:
(+ 1 8388607)
=> -8388608
=> 1000 0000 0000 0000 0000 0000
Many of the following functions accept markers for arguments as well
as integers. (*Note Markers::.) More accurately, the actual parameters
to such functions may be integers or markers; and MARKER-OR-INT
specifies the formal parameter. When the actual parameter is a marker,
the position value of the marker is used and the buffer of the marker is
ignored.
In version 19, except where *integer* is specified as an argument, all
of the functions for markers and integers also work for floating point
numbers.
▶1f◀
File: lispref Node: Predicates on Numbers, Prev: Number Basics, Up: Numbers, Next: Comparison of Numbers
Type Predicates for Numbers
===========================
The `integerp' and `floatp' predicates test whether the argument is an
integer or floating point number, respectively. Note that these
functions and the `natnump' predicate can take any type of Lisp object
as argument (the predicates would not be of much use otherwise); but the
`zerop' predicate requires an integer as its argument.
* Function: floatp OBJECT
This predicate tests to see whether its argument is a floating
point number and returns `t' if so, `nil' otherwise.
`floatp' is part of version 19 Emacs, not version 18.
* Function: integerp OBJECT
This predicate tests to see whether its argument is an integer (a
whole number) and returns `t' if so, `nil' otherwise.
* Function: natnump OBJECT
The `natnump' predicate (whose name comes from the phrase
``natural-number-p'') tests to see whether its argument is a
nonnegative (i.e., natural) integer, and returns `t' if so, `nil'
otherwise. 0 is considered non-negative.
Markers are not converted to integers, hence `natnump' of a marker
is always `nil'.
* Function: zerop INTEGER
This predicate tests to see whether its argument is zero, and
returns `t' if so, `nil' otherwise. These two forms are
equivalent: `(zerop x) == (= x 0)'.
▶1f◀
File: lispref Node: Comparison of Numbers, Prev: Predicates on Numbers, Up: Numbers, Next: Arithmetic Operations
Comparison of Numbers
=====================
The integer type is implemented by storing the value in the ``pointer
part'' of a Lisp object pointer (which, in the canonical case, has 24
bits of pointer, 7 bits of type and 1 bit for the garbage collector).
Because of this, the function `eq' will return `t' for two integers with
the same value. *Note Equality Predicates::.
Common Lisp Note: Because of the way numbers are implemented in
Common Lisp, you generally need to use ``='' to test for equality
between numbers. However, GNU Emacs Lisp does not need very large
integers; as a consequence, it is possible to restrict them to the
size of a single word, allowing `eq' to be used.
* Function: = MARKER-OR-INT1 MARKER-OR-INT2
This function tests to see whether its arguments are the same
number, and returns `t' if so, `nil' otherwise.
* Function: /= MARKER-OR-INT1 MARKER-OR-INT2
This function tests to see whether its arguments are not the same
number, and returns `t' if so, `nil' otherwise.
* Function: < MARKER-OR-INT1 MARKER-OR-INT2
This function tests to see whether its first argument is strictly
less than its second argument. It returns `t' if so, `nil'
otherwise.
* Function: <= MARKER-OR-INT1 MARKER-OR-INT2
This function tests to see whether its first argument is less
than or equal to its second argument. It returns `t' if so, `nil'
otherwise.
* Function: > MARKER-OR-INT1 MARKER-OR-INT2
This function tests to see whether its first argument is strictly
greater than its second argument. It returns `t' if so, `nil'
otherwise.
* Function: >= MARKER-OR-INT1 MARKER-OR-INT2
This function tests to see whether its first argument is greater
than or equal to its second argument. It returns `t' if so, `nil'
otherwise.
* Function: max MARKER-OR-INT &rest MARKER-OR-INTS
This function returns the largest of its arguments.
(max 20)
=> 20
(max 1 2)
=> 2
(max 1 3 2)
=> 3
* Function: min MARKER-OR-INT &rest MARKER-OR-INTS
This function returns the smallest of its arguments.
▶1f◀
File: lispref Node: Arithmetic Operations, Prev: Comparison of Numbers, Up: Numbers, Next: Bitwise Operations on Integers
Arithmetic Operations
=====================
Emacs Lisp provides the traditional four arithmetic operations:
addition, subtraction, multiplication, and division. A remainder
function supplements the (integer) division function. In addition, as a
convenience, incrementing and decrementing functions are provided.
It is important to note that in GNU Emacs Lisp, arithmetic functions
do not check for overflow. Thus (1+ 8388607) may equal -8388608,
depending on your hardware.
* Function: 1+ MARKER-OR-INT
This function adds one to MARKER-OR-INT.
* Function: 1- MARKER-OR-INT
This function subtracts one from MARKER-OR-INT.
* Function: + &rest INTEGERS
This function adds its arguments together. When given no
arguments, `+' returns 0. It does not check for overflow.
(+)
=> 0
(+ 1)
=> 1
(+ 1 2 3 4)
=> 10
* Function: - &optional INTEGER &rest OTHER-INTEGERS
The `-' function serves two purposes: negation and subtraction.
When `-' has a single argument, the value is the negative of the
argument.
When there are multiple arguments, each of the OTHER-INTEGERS is
subtracted from INTEGER, cumulatively. If there are no arguments,
the result is `0'.
(- 10 1 2 3 4)
=> 0
(- 10)
=> -10
(-)
=> 0
* Function: * &rest INTEGERS
This function multiplies its arguments together, and returns the
product. When given no arguments, `*' returns `1'. It does not
check for overflow.
(*)
=> 1
(* 1)
=> 1
(* 1 2 3 4)
=> 24
* Function: / DIVIDEND DIVISOR &rest OTHER-INTEGERS
This function divides DIVIDEND by DIVISOR, and returns the
quotient. If there are more arguments, then they are each used to
divide the previous result. The result is always rounded down
after each division.
If you divide a numerator by `0', an `arith-error' results. (*Note
Errors::.)
(/ 6 2)
=> 3
(/ 5 2)
=> 2
(/ 25 3 2)
=> 4
(/ -17 6)
=> -2 ; (Could be -3 on some machines.)
* Function: % DIVIDEND DIVISOR
This function returns the value of DIVIDEND modulo DIVISOR, or in
other words, the integer remainder after division of DIVIDEND by
DIVISOR. The sign of the result is the sign of DIVIDEND. The sign
of DIVISOR is ignored.
An `arith-error' results if DIVISOR = `0'.
(% 9 4)
=> 1
(% -9 4)
=> -1
(% 9 -4)
=> 1
(% -9 -4)
=> -1
▶1f◀
File: lispref Node: Bitwise Operations on Integers, Prev: Arithmetic Operations, Up: Numbers, Next: Random Numbers
Bitwise Operations on Integers
==============================
In a computer, an integer is a binary number, a pattern of zeros and
ones. A bitwise operation transforms such a pattern. For example, a
shift moves the whole pattern left or right one or more places,
reproducing the same pattern `moved over'.
The following bitwise operations apply only to integers.
* Function: lsh INTEGER1 INTEGER2
`lsh', which is an abbreviation for "logical shift", shifts the
bits in INTEGER1 to the left INTEGER2 places, or to the right if
INTEGER2 is negative. If both arguments are negative, `lsh' shifts
in zeros. See `ash' below.
Thus, the decimal number 5 is the binary number `00000101'.
Shifted once to the left, with a zero put in the one's place, the
number becomes `00001010', decimal 10.
Here are two examples of shifting the pattern of bits one place to
the left. Since the contents of the right-most place has been
moved one place to the left, a value has to be inserted into the
right-most place. With `lsh', a zero is placed into the right-most
place. (In these examples, the binary pattern is only eight bits
long. See `ash' for examples illustrating the full twenty-four
bits of an Emacs Lisp integer.)
(lsh 5 1)
=> 10
00000101 =>
(lsh 7 1)
=> 14
00000111 => 00001110 ; Decimal 7 becomes decimal 14.
As the examples illustrate, shifting the pattern of bits one place
to the left produces a number that is twice the value of the
previous number.
Note, however that functions do not check for overflow, and a
returned value may be negative (and in any case, no more than a 24
bit value) when an integer is sufficiently left shifted. For
example:
(lsh 8388607 1) ; left shift
=> -2
In binary, in the 24 bit implementation,
0111 1111 1111 1111 1111 1111 ; decimal 8,388,607
becomes
1111 1111 1111 1111 1111 1110 ; decimal -2
Shifting the pattern of bits two places to the left produces
results like this (with 8-bit binary numbers):
(lsh 3 2)
=> 12
00000011 => 00001100 ; Decimal 3 becomes decimal 12.
On the other hand, shifting the pattern of bits one place to the
right looks like this:
(lsh 6 -1)
=> 3
00000110 => 00000011 ; Decimal 6 becomes decimal 3.
(lsh 5 -1)
=> 2
00000101 => 00000010 ; Decimal 5 becomes decimal 2.
As the example illustrates, shifting the pattern of bits one place
to the right divides the value of the binary number in half (or
less then half if the orignal right-most digit is a 1 that is
lost).
* Function: ash INTEGER1 INTEGER2
`ash' ("arithmetic shift") shifts the bits in INTEGER1 to the left
INTEGER2 places, or to the right if INTEGER2 is negative.
`ash' gives the same results as `lsh' except when INTEGER1 and
INTEGER2 are both negative. In that case, `ash' puts a one in the
left-most position, while `lsh' puts a zero in the left-most
position.
Thus, with `ash', shifting the pattern of bits one place to the
right looks like this:
(ash -6 -1)
=> -3 ; Decimal -6 becomes decimal -3.
1111 1111 1111 1111 1111 1010
=>
1111 1111 1111 1111 1111 1101
In contrast, shifting the pattern of bits one place to the right
with `lsh' looks like this:
(lsh -6 -1)
=> 8388605 ; Decimal -6 becomes decimal 8,288,605.
1111 1111 1111 1111 1111 1010
=>
0111 1111 1111 1111 1111 1101
In this case, the 1 in the left-most position is shifted one place
to the right, and a zero is shifted into the left-most position.
Here are other examples:
; 24-bit binary values
(lsh 5 2) ; 5 = 0000 0000 0000 0000 0000 0101
=> 20 ; 20 = 0000 0000 0000 0000 0001 0100
(ash 5 2)
=> 20
(lsh -5 2) ; -5 = 1111 1111 1111 1111 1111 1011
=> -20 ; -20 = 1111 1111 1111 1111 1110 1100
(ash -5 2)
=> -20
(lsh 5 -2) ; 5 = 0000 0000 0000 0000 0000 0101
=> 1 ; 1 = 0000 0000 0000 0000 0000 0001
(ash 5 -2)
=> 1
(lsh -5 -2 ) ; -5 = 1111 1111 1111 1111 1111 1011
=> 4194302 ; 0011 1111 1111 1111 1111 1110
(ash -5 -2) ; -5 = 1111 1111 1111 1111 1111 1011
=> -2 ; -2 = 1111 1111 1111 1111 1111 1110
* Function: logand &rest MARKER-OR-INTS
This function returns the ``logical and'' of the arguments: the
N'th bit is set in the result if, and only if, the N'th bit is set
in all the arguments. ``Set'' means that the value of the bit is 1
rather than 0.
For example, using 4-bit binary numbers, the ``logical and'' of 13
and 12 is 12:
1101
1100
=> 1100
In both the binary numbers, the two left-most bits are set (i.e.,
they are 1's), so the two left-most bits of the returned value are
set. But both of the two right-most bits are not set, so the two
right-most bits of the returned value are 0's.
Restating that example in decimal numbers,
(logand 13 12)
=> 12
If `logand' is not passed any argument, it returns a value of
`-1', the number which consists entirely of ones.
For `logand', `logior', and `logxor', if there is only one
argument, that argument is the result.
; 24-bit binary values
(logand 14 13) ; 14 = 0000 0000 0000 0000 0000 1110
; 13 = 0000 0000 0000 0000 0000 1101
=> 12 ; 12 = 0000 0000 0000 0000 0000 1100
(logand 14 13 4) ; 14 = 0000 0000 0000 0000 0000 1110
; 13 = 0000 0000 0000 0000 0000 1101
=> 4 ; 4 = 0000 0000 0000 0000 0000 0100
(logand)
-1 ; -1 = 1111 1111 1111 1111 1111 1111
* Function: logior &rest MARKER-OR-INTS
This function returns the ``inclusive or'' of it arguments: the
n'th bit is set in the result if, and only if, the n'th bit is set
in at least one of the arguments. If there are no arguments, the
result is `0'.
; 24-bit binary values
(logior 12 5) ; 12 = 0000 0000 0000 0000 0000 1100
; 5 = 0000 0000 0000 0000 0000 0101
=> 13 ; 13 = 0000 0000 0000 0000 0000 1101
(logior 12 5 7) ; 12 = 0000 0000 0000 0000 0000 1100
; 5 = 0000 0000 0000 0000 0000 0101
; 7 = 0000 0000 0000 0000 0000 0111
=> 15 ; 15 = 0000 0000 0000 0000 0000 1111
* Function: logxor &rest MARKER-OR-INTS
This function returns the ``exclusive or'' of its arguments: the
N'th bit is set in the result if, and only if, the N'th bit is set
in an odd number of the arguments. If there are no arguments, the
result is 0.
; 24-bit binary values
(logxor 12 5) ; 12 = 0000 0000 0000 0000 0000 1100
; 5 = 0000 0000 0000 0000 0000 0101
=> 9 ; 9 = 0000 0000 0000 0000 0000 1001
(logxor 12 5 7) ; 12 = 0000 0000 0000 0000 0000 1100
; 5 = 0000 0000 0000 0000 0000 0101
; 7 = 0000 0000 0000 0000 0000 0111
=> 14 ; 14 = 0000 0000 0000 0000 0000 1110
* Function: lognot INTEGER
This function returns the logical complement of its argument: the
N'th bit is one in the result if, and only if, the N'th bit is zero
in INTEGER, and vice-versa.
(lognot 5) ; 5 = 0000 0000 0000 0000 0000 0101
=> -6 ; -6 = 1111 1111 1111 1111 1111 1010
▶1f◀
File: lispref Node: Random Numbers, Prev: Bitwise Operations on Integers, Up: Numbers
Random Numbers
==============
* Function: random &optional FLAG
This function returns a pseudo-random number of type integer.
When called more than once, this function returns a series of
pseudo-random numbers.
In a computer, such a series of a pseudo-random numbers is
generated in a deterministic fashion. As its name indicates, a
pseudo-random number is not a random number. However, a
pseudo-random series of numbers has properties that mimic a truly
random series in many ways. For example, in a pseudo-random
series, no number is supposed to appear more frequently that it
would in a truly random series.
A series of pseudo-random numbers is generated from a `seed'
number that is derived from some changing value such as the time of
day. If the `random' function starts with the same seed, it
generates the same sequence of numbers.
On some machines, any integer representable in Lisp may be the
result of `random'. On other machines, the result can never be
larger than a certain maximum or less than a certain (negative)
minimum.
When a pseudo-random series of numbers is generated, any of the
possible values has the same probability of being returned as any
other possible value.
If you want random numbers that are different each time you run
Emacs, use `(random t)' in your code at least once. This
reinitializes the pseudo-random number seed based on the current
time of day and on Emacs' process ID number.
Put another way, the sequence of numbers returned by `random' is
the same in each Emacs run, unless you use `(random t)'. For
example, in one operating system, the first call to `(random)'
after you start Emacs always returns `-1457731', and the second one
always returns `-7692030'. Therefore, programs that use `random'
are repeatable, unless you evaluate `(random t)'. This is helpful
when you are debugging.
▶1f◀
File: lispref Node: Strings and Characters, Prev: Numbers, Up: Top, Next: Lists
Strings and Characters
**********************
Strings are used to send messages to users, to hold extracts from
buffers, and for many other purposes. The print names of symbols are
strings. Because strings are so important, a large number of functions
are provided expressly for manipulating them. In Emacs Lisp,
programmers often use strings, but they seldom use characters, except
when defining keymaps.
The length of a string (like any array) is fixed, and cannot be
altered. In particular, strings in Lisp are *not* terminated by any
particular character, such as ASCII code 0, as they are in C. This
means that any character, including the null character (ASCII code 0),
is a valid element of a string.
Since strings are considered arrays, you can operate on them with the
general array functions. (*Note Sequences Arrays Vectors::.) For
example, you can access or change individual characters in a string by
using the `aref' and `aset' functions (*Note Arrays::).
On the other hand, although strings are considered arrays, they
require only 8 bits for each element rather than a minimum of 32. This
means that a string takes up much less memory than a vector of the same
length.
*Note Text::, for information about functions that display strings or
copy them into buffers.
*Note Character Type::, and *Note String Type::, for information about
the syntax of characters and strings.
* Menu:
* Predicates for Strings::
* Creating Strings::
* Comparison of Characters and Strings::
* Conversion of Characters and Strings::
* Character Case::
▶1f◀