Mercurial > emacs
changeset 6510:e18202af3602
Initial revision
| author | Richard M. Stallman <rms@gnu.org> |
|---|---|
| date | Thu, 24 Mar 1994 17:24:15 +0000 |
| parents | 9ab67b3b597a |
| children | fb1c6b7aba39 |
| files | lispref/numbers.texi lispref/variables.texi |
| diffstat | 2 files changed, 2292 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/numbers.texi Thu Mar 24 17:24:15 1994 +0000 @@ -0,0 +1,1030 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/numbers +@node Numbers, Strings and Characters, Types of Lisp Object, Top +@chapter Numbers +@cindex integers +@cindex numbers + + GNU Emacs supports two numeric data types: @dfn{integers} and +@dfn{floating point numbers}. Integers are whole numbers such as +@minus{}3, 0, 7, 13, and 511. Their values are exact. Floating point +numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or +2.71828. They can also be expressed in an exponential notation as well: +thus, 1.5e2 equals 150; in this example, @samp{e2} stands for ten to the +second power, and is multiplied by 1.5. Floating point values are not +exact; they have a fixed, limited amount of precision. + + Support for floating point numbers is a new feature in Emacs 19, and it +is controlled by a separate compilation option, so you may encounter a site +where Emacs does not support them. + +@menu +* Integer Basics:: Representation and range of integers. +* Float Basics:: Representation and range of floating point. +* Predicates on Numbers:: Testing for numbers. +* Comparison of Numbers:: Equality and inequality predicates. +* Numeric Conversions:: Converting float to integer and vice versa. +* Arithmetic Operations:: How to add, subtract, multiply and divide. +* Rounding Operations:: Explicitly rounding floating point numbers. +* Bitwise Operations:: Logical and, or, not, shifting. +* Transcendental Functions:: Trig, exponential and logarithmic functions. +* Random Numbers:: Obtaining random integers, predictable or not. +@end menu + +@node Integer Basics +@comment node-name, next, previous, up +@section Integer Basics + + The range of values for an integer depends on the machine. The +range is @minus{}8388608 to 8388607 (24 bits; i.e., +@ifinfo +-2**23 +@end ifinfo +@tex +$-2^{23}$ +@end tex +to +@ifinfo +2**23 - 1) +@end ifinfo +@tex +$2^{23}-1$) +@end tex +on most machines, but on others it is @minus{}16777216 to 16777215 (25 +bits), or @minus{}33554432 to 33554431 (26 bits). Many examples in this +chapter assume an integer has 24 bits. +@cindex overflow + + The Lisp reader reads an integer as a sequence of digits with optional +initial sign and optional final period. + +@example + 1 ; @r{The integer 1.} + 1. ; @r{The integer 1.} ++1 ; @r{Also the integer 1.} +-1 ; @r{The integer @minus{}1.} + 16777217 ; @r{Also the integer 1, due to overflow.} + 0 ; @r{The integer 0.} +-0 ; @r{The integer 0.} +@end example + + To understand how various functions work on integers, especially the +bitwise operators (@pxref{Bitwise Operations}), it is often helpful to +view the numbers in their binary form. + + In 24 bit binary, the decimal integer 5 looks like this: + +@example +0000 0000 0000 0000 0000 0101 +@end example + +@noindent +(We have inserted spaces between groups of 4 bits, and two spaces +between groups of 8 bits, to make the binary integer easier to read.) + + The integer @minus{}1 looks like this: + +@example +1111 1111 1111 1111 1111 1111 +@end example + +@noindent +@cindex two's complement +@minus{}1 is represented as 24 ones. (This is called @dfn{two's +complement} notation.) + + The negative integer, @minus{}5, is creating by subtracting 4 from +@minus{}1. In binary, the decimal integer 4 is 100. Consequently, +@minus{}5 looks like this: + +@example +1111 1111 1111 1111 1111 1011 +@end example + + In this implementation, the largest 24 bit binary integer is the +decimal integer 8,388,607. In binary, it looks like this: + +@example +0111 1111 1111 1111 1111 1111 +@end example + + Since the arithmetic functions do not check whether integers go +outside their range, when you add 1 to 8,388,607, the value is negative +integer @minus{}8,388,608: + +@example +(+ 1 8388607) + @result{} -8388608 + @result{} 1000 0000 0000 0000 0000 0000 +@end example + + Many of the following functions accept markers for arguments as well +as integers. (@xref{Markers}.) More precisely, the actual arguments to +such functions may be either integers or markers, which is why we often +give these arguments the name @var{int-or-marker}. When the argument +value is a marker, its position value is used and its buffer is ignored. + +@ignore + In version 19, except where @emph{integer} is specified as an +argument, all of the functions for markers and integers also work for +floating point numbers. +@end ignore + +@node Float Basics +@section Floating Point Basics + +@cindex @code{LISP_FLOAT_TYPE} configuration macro + Emacs version 19 supports floating point numbers, if compiled with the +macro @code{LISP_FLOAT_TYPE} defined. The precise range of floating +point numbers is machine-specific; it is the same as the range of the C +data type @code{double} on the machine in question. + + The printed representation for floating point numbers requires either +a decimal point (with at least one digit following), an exponent, or +both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, +@samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point +number whose value is 1500. They are all equivalent. You can also use +a minus sign to write negative floating point numbers, as in +@samp{-1.0}. + +@cindex IEEE floating point +@cindex positive infinity +@cindex negative infinity +@cindex infinity +@cindex NaN + Most modern computers support the IEEE floating point standard, which +provides for positive infinity and negative infinity as floating point +values. It also provides for a value called NaN or ``not-a-number'' +which is the result you get from numerical functions in cases where +there is no correct answer. For example, @code{(sqrt -1.0)} returns +NaN. There is no read syntax for NaN or infinities; perhaps we should +create a syntax in the future. + + You can use @code{logb} to extract the binary exponent of a floating +point number (or estimate the logarithm of an integer): + +@defun logb number +This function returns the binary exponent of @var{number}. More +precisely, the value is the logarithm of @var{number} base 2, rounded +down to an integer. +@end defun + +@node Predicates on Numbers +@section Type Predicates for Numbers + + The functions in this section test whether the argument is a number or +whether it is a certain sort of number. The functions @code{integerp} +and @code{floatp} can take any type of Lisp object as argument (the +predicates would not be of much use otherwise); but the @code{zerop} +predicate requires a number as its argument. See also +@code{integer-or-marker-p} and @code{number-or-marker-p}, in +@ref{Predicates on Markers}. + +@defun floatp object +This predicate tests whether its argument is a floating point +number and returns @code{t} if so, @code{nil} otherwise. + +@code{floatp} does not exist in Emacs versions 18 and earlier. +@end defun + +@defun integerp object +This predicate tests whether its argument is an integer, and returns +@code{t} if so, @code{nil} otherwise. +@end defun + +@defun numberp object +This predicate tests whether its argument is a number (either integer or +floating point), and returns @code{t} if so, @code{nil} otherwise. +@end defun + +@defun natnump object +@cindex natural numbers +The @code{natnump} predicate (whose name comes from the phrase +``natural-number-p'') tests to see whether its argument is a nonnegative +integer, and returns @code{t} if so, @code{nil} otherwise. 0 is +considered non-negative. + +Markers are not converted to integers, hence @code{natnump} of a marker +is always @code{nil}. + +People have pointed out that this function is misnamed, because the term +``natural number'' is usually understood as excluding zero. We are open +to suggestions for a better name to use in a future version. +@end defun + +@defun zerop number +This predicate tests whether its argument is zero, and returns @code{t} +if so, @code{nil} otherwise. The argument must be a number. + +These two forms are equivalent: @code{(zerop x)} @equiv{} @code{(= x 0)}. +@end defun + +@node Comparison of Numbers +@section Comparison of Numbers +@cindex number equality + + Floating point numbers in Emacs Lisp actually take up storage, and +there can be many distinct floating point number objects with the same +numeric value. If you use @code{eq} to compare them, then you test +whether two values are the same @emph{object}. If you want to test for +numerical equality, use @code{=}. + + If you use @code{eq} to compare two integers, it always returns +@code{t} if they have the same value. This is sometimes useful, because +@code{eq} accepts arguments of any type and never causes an error, +whereas @code{=} signals an error if the arguments are not numbers or +markers. However, it is a good idea to use @code{=} if you can, even +for comparing integers, just in case we change the representation of +integers in a future Emacs version. + + There is another wrinkle: because floating point arithmetic is not +exact, it is often a bad idea to check for equality of two floating +point values. Usually it is better to test for approximate equality. +Here's a function to do this: + +@example +(defvar fuzz-factor 1.0e-6) +(defun approx-equal (x y) + (< (/ (abs (- x y)) + (max (abs x) (abs y))) + fuzz-factor)) +@end example + +@cindex CL note---integers vrs @code{eq} +@quotation +@b{Common Lisp note:} comparing numbers in Common Lisp always requires +@code{=} because Common Lisp implements multi-word integers, and two +distinct integer objects can have the same numeric value. Emacs Lisp +can have just one integer object for any given value because it has a +limited range of integer values. +@end quotation + +@defun = number-or-marker1 number-or-marker2 +This function tests whether its arguments are numerically equal, and +returns @code{t} if so, @code{nil} otherwise. +@end defun + +@defun /= number-or-marker1 number-or-marker2 +This function tests whether its arguments are numerically equal, and +returns @code{t} if they are not, and @code{nil} if they are. +@end defun + +@defun < number-or-marker1 number-or-marker2 +This function tests whether its first argument is strictly less than +its second argument. It returns @code{t} if so, @code{nil} otherwise. +@end defun + +@defun <= number-or-marker1 number-or-marker2 +This function tests whether its first argument is less than or equal +to its second argument. It returns @code{t} if so, @code{nil} +otherwise. +@end defun + +@defun > number-or-marker1 number-or-marker2 +This function tests whether its first argument is strictly greater +than its second argument. It returns @code{t} if so, @code{nil} +otherwise. +@end defun + +@defun >= number-or-marker1 number-or-marker2 +This function tests whether its first argument is greater than or +equal to its second argument. It returns @code{t} if so, @code{nil} +otherwise. +@end defun + +@defun max number-or-marker &rest numbers-or-markers +This function returns the largest of its arguments. + +@example +(max 20) + @result{} 20 +(max 1 2.5) + @result{} 2.5 +(max 1 3 2.5) + @result{} 3 +@end example +@end defun + +@defun min number-or-marker &rest numbers-or-markers +This function returns the smallest of its arguments. + +@example +(min -4 1) + @result{} -4 +@end example +@end defun + +@node Numeric Conversions +@section Numeric Conversions +@cindex rounding in conversions + +To convert an integer to floating point, use the function @code{float}. + +@defun float number +This returns @var{number} converted to floating point. +If @var{number} is already a floating point number, @code{float} returns +it unchanged. +@end defun + +There are four functions to convert floating point numbers to integers; +they differ in how they round. These functions accept integer arguments +also, and return such arguments unchanged. + +@defun truncate number +This returns @var{number}, converted to an integer by rounding towards +zero. +@end defun + +@defun floor number &optional divisor +This returns @var{number}, converted to an integer by rounding downward +(towards negative infinity). + +If @var{divisor} is specified, @var{number} is divided by @var{divisor} +before the floor is taken; this is the division operation that +corresponds to @code{mod}. An @code{arith-error} results if +@var{divisor} is 0. +@end defun + +@defun ceiling number +This returns @var{number}, converted to an integer by rounding upward +(towards positive infinity). +@end defun + +@defun round number +This returns @var{number}, converted to an integer by rounding towards the +nearest integer. +@end defun + +@node Arithmetic Operations +@section Arithmetic Operations + + Emacs Lisp provides the traditional four arithmetic operations: +addition, subtraction, multiplication, and division. Remainder and modulus +functions supplement the division functions. The functions to +add or subtract 1 are provided because they are traditional in Lisp and +commonly used. + + All of these functions except @code{%} return a floating point value +if any argument is floating. + + It is important to note that in GNU Emacs Lisp, arithmetic functions +do not check for overflow. Thus @code{(1+ 8388607)} may evaluate to +@minus{}8388608, depending on your hardware. + +@defun 1+ number-or-marker +This function returns @var{number-or-marker} plus 1. +For example, + +@example +(setq foo 4) + @result{} 4 +(1+ foo) + @result{} 5 +@end example + +This function is not analogous to the C operator @code{++}---it does +not increment a variable. It just computes a sum. Thus, + +@example +foo + @result{} 4 +@end example + +If you want to increment the variable, you must use @code{setq}, +like this: + +@example +(setq foo (1+ foo)) + @result{} 5 +@end example +@end defun + +@defun 1- number-or-marker +This function returns @var{number-or-marker} minus 1. +@end defun + +@defun abs number +This returns the absolute value of @var{number}. +@end defun + +@defun + &rest numbers-or-markers +This function adds its arguments together. When given no arguments, +@code{+} returns 0. It does not check for overflow. + +@example +(+) + @result{} 0 +(+ 1) + @result{} 1 +(+ 1 2 3 4) + @result{} 10 +@end example +@end defun + +@defun - &optional number-or-marker &rest other-numbers-or-markers +The @code{-} function serves two purposes: negation and subtraction. +When @code{-} has a single argument, the value is the negative of the +argument. When there are multiple arguments, @code{-} subtracts each of +the @var{other-numbers-or-markers} from @var{number-or-marker}, +cumulatively. If there are no arguments, the result is 0. This +function does not check for overflow. + +@example +(- 10 1 2 3 4) + @result{} 0 +(- 10) + @result{} -10 +(-) + @result{} 0 +@end example +@end defun + +@defun * &rest numbers-or-markers +This function multiplies its arguments together, and returns the +product. When given no arguments, @code{*} returns 1. It does +not check for overflow. + +@example +(*) + @result{} 1 +(* 1) + @result{} 1 +(* 1 2 3 4) + @result{} 24 +@end example +@end defun + +@defun / dividend divisor &rest divisors +This function divides @var{dividend} by @var{divisors} and returns the +quotient. If there are additional arguments @var{divisors}, then it +divides @var{dividend} by each divisor in turn. Each argument may be a +number or a marker. + +If all the arguments are integers, then the result is an integer too. +This means the result has to be rounded. On most machines, the result +is rounded towards zero after each division, but some machines may round +differently with negative arguments. This is because the Lisp function +@code{/} is implemented using the C division operator, which also +permits machine-dependent rounding. As a practical matter, all known +machines round in the standard fashion. + +@cindex @code{arith-error} in division +If you divide by 0, an @code{arith-error} error is signaled. +(@xref{Errors}.) + +@example +(/ 6 2) + @result{} 3 +(/ 5 2) + @result{} 2 +(/ 25 3 2) + @result{} 4 +(/ -17 6) + @result{} -2 +@end example + +The result of @code{(/ -17 6)} could in principle be -3 on some +machines. +@end defun + +@defun % dividend divisor +@cindex remainder +This function returns the integer remainder after division of @var{dividend} +by @var{divisor}. The arguments must be integers or markers. + +For negative arguments, the remainder is in principle machine-dependent +since the quotient is; but in practice, all known machines behave alike. + +An @code{arith-error} results if @var{divisor} is 0. + +@example +(% 9 4) + @result{} 1 +(% -9 4) + @result{} -1 +(% 9 -4) + @result{} 1 +(% -9 -4) + @result{} -1 +@end example + +For any two integers @var{dividend} and @var{divisor}, + +@example +@group +(+ (% @var{dividend} @var{divisor}) + (* (/ @var{dividend} @var{divisor}) @var{divisor})) +@end group +@end example + +@noindent +always equals @var{dividend}. +@end defun + +@defun mod dividend divisor +@cindex modulus +This function returns the value of @var{dividend} modulo @var{divisor}; +in other words, the remainder after division of @var{dividend} +by @var{divisor}, but with the same sign as @var{divisor}. +The arguments must be numbers or markers. + +Unlike @code{%}, @code{mod} returns a well-defined result for negative +arguments. It also permits floating point arguments; it rounds the +quotient downward (towards minus infinity) to an integer, and uses that +quotient to compute the remainder. + +An @code{arith-error} results if @var{divisor} is 0. + +@example +(mod 9 4) + @result{} 1 +(mod -9 4) + @result{} 3 +(mod 9 -4) + @result{} -3 +(mod -9 -4) + @result{} -1 +(mod 5.5 2.5) + @result{} .5 +@end example + +For any two numbers @var{dividend} and @var{divisor}, + +@example +@group +(+ (mod @var{dividend} @var{divisor}) + (* (floor @var{dividend} @var{divisor}) @var{divisor})) +@end group +@end example + +@noindent +always equals @var{dividend}, subject to rounding error if +either argument is floating point. +@end defun + +@node Rounding Operations +@section Rounding Operations +@cindex rounding without conversion + +The functions @code{ffloor}, @code{fceil}, @code{fround} and +@code{ftruncate} take a floating point argument and return a floating +point result whose value is a nearby integer. @code{ffloor} returns the +nearest integer below; @code{fceil}, the nearest integer above; +@code{ftrucate}, the nearest integer in the direction towards zero; +@code{fround}, the nearest integer. + +@defun ffloor float +This function rounds @var{float} to the next lower integral value, and +returns that value as a floating point number. +@end defun + +@defun fceil float +This function rounds @var{float} to the next higher integral value, and +returns that value as a floating point number. +@end defun + +@defun ftrunc float +This function rounds @var{float} towards zero to an integral value, and +returns that value as a floating point number. +@end defun + +@defun fround float +This function rounds @var{float} to the nearest integral value, +and returns that value as a floating point number. +@end defun + +@node Bitwise Operations +@section Bitwise Operations on Integers + + In a computer, an integer is represented as a binary number, a +sequence of @dfn{bits} (digits which are either zero or one). A bitwise +operation acts on the individual bits of such a sequence. For example, +@dfn{shifting} moves the whole sequence left or right one or more places, +reproducing the same pattern ``moved over''. + + The bitwise operations in Emacs Lisp apply only to integers. + +@defun lsh integer1 count +@cindex logical shift +@code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the +bits in @var{integer1} to the left @var{count} places, or to the +right if @var{count} is negative. If @var{count} is negative, +@code{lsh} shifts zeros into the most-significant bit, producing a +positive result even if @var{integer1} is negative. Contrast this with +@code{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 rightmost place has been moved one +place to the left, a value has to be inserted into the rightmost place. +With @code{lsh}, a zero is placed into the rightmost place. (These +examples show only the low-order eight bits of the binary pattern; the +rest are all zero.) + +@example +@group +(lsh 5 1) + @result{} 10 +;; @r{Decimal 5 becomes decimal 10.} +00000101 @result{} 00001010 + +(lsh 7 1) + @result{} 14 +;; @r{Decimal 7 becomes decimal 14.} +00000111 @result{} 00001110 +@end group +@end example + +@noindent +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, left shifting 8,388,607 produces @minus{}2: + +@example +(lsh 8388607 1) ; @r{left shift} + @result{} -2 +@end example + +In binary, in the 24 bit implementation, the numbers looks like this: + +@example +@group +;; @r{Decimal 8,388,607} +0111 1111 1111 1111 1111 1111 +@end group +@end example + +@noindent +which becomes the following when left shifted: + +@example +@group +;; @r{Decimal @minus{}2} +1111 1111 1111 1111 1111 1110 +@end group +@end example + +Shifting the pattern of bits two places to the left produces results +like this (with 8-bit binary numbers): + +@example +@group +(lsh 3 2) + @result{} 12 +;; @r{Decimal 3 becomes decimal 12.} +00000011 @result{} 00001100 +@end group +@end example + +On the other hand, shifting the pattern of bits one place to the right +looks like this: + +@example +@group +(lsh 6 -1) + @result{} 3 +;; @r{Decimal 6 becomes decimal 3.} +00000110 @result{} 00000011 +@end group + +@group +(lsh 5 -1) + @result{} 2 +;; @r{Decimal 5 becomes decimal 2.} +00000101 @result{} 00000010 +@end group +@end example + +@noindent +As the example illustrates, shifting the pattern of bits one place to +the right divides the value of the binary number by two, rounding downward. +@end defun + +@defun ash integer1 count +@cindex arithmetic shift +@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1} +to the left @var{count} places, or to the right if @var{count} +is negative. + +@code{ash} gives the same results as @code{lsh} except when +@var{integer1} and @var{count} are both negative. In that case, +@code{ash} puts a one in the leftmost position, while @code{lsh} puts +a zero in the leftmost position. + +Thus, with @code{ash}, shifting the pattern of bits one place to the right +looks like this: + +@example +@group +(ash -6 -1) @result{} -3 +;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} +1111 1111 1111 1111 1111 1010 + @result{} +1111 1111 1111 1111 1111 1101 +@end group +@end example + +In contrast, shifting the pattern of bits one place to the right with +@code{lsh} looks like this: + +@example +@group +(lsh -6 -1) @result{} 8388605 +;; @r{Decimal @minus{}6 becomes decimal 8,388,605.} +1111 1111 1111 1111 1111 1010 + @result{} +0111 1111 1111 1111 1111 1101 +@end group +@end example + +@noindent +In this case, the 1 in the leftmost position is shifted one place to the +right, and a zero is shifted into the leftmost position. + +Here are other examples: + +@c !!! Check if lined up in smallbook format! XDVI shows problem +@c with smallbook but not with regular book! --rjc 16mar92 +@smallexample +@group + ; @r{ 24-bit binary values} + +(lsh 5 2) ; 5 = @r{0000 0000 0000 0000 0000 0101} + @result{} 20 ; 20 = @r{0000 0000 0000 0000 0001 0100} +@end group +@group +(ash 5 2) + @result{} 20 +(lsh -5 2) ; -5 = @r{1111 1111 1111 1111 1111 1011} + @result{} -20 ; -20 = @r{1111 1111 1111 1111 1110 1100} +(ash -5 2) + @result{} -20 +@end group +@group +(lsh 5 -2) ; 5 = @r{0000 0000 0000 0000 0000 0101} + @result{} 1 ; 1 = @r{0000 0000 0000 0000 0000 0001} +@end group +@group +(ash 5 -2) + @result{} 1 +@end group +@group +(lsh -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1011} + @result{} 4194302 ; @r{0011 1111 1111 1111 1111 1110} +@end group +@group +(ash -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1011} + @result{} -2 ; -2 = @r{1111 1111 1111 1111 1111 1110} +@end group +@end smallexample +@end defun + +@defun logand &rest ints-or-markers +@cindex logical and +@cindex bitwise and +This function returns the ``logical and'' of the arguments: the +@var{n}th bit is set in the result if, and only if, the @var{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 combined with 1100 produces 1100. + +In both the binary numbers, the leftmost two bits are set (i.e., they +are 1's), so the leftmost two bits of the returned value are set. +However, for the rightmost two bits, each is zero in at least one of +the arguments, so the rightmost two bits of the returned value are 0's. + +@noindent +Therefore, + +@example +@group +(logand 13 12) + @result{} 12 +@end group +@end example + +If @code{logand} is not passed any argument, it returns a value of +@minus{}1. This number is an identity element for @code{logand} +because its binary representation consists entirely of ones. If +@code{logand} is passed just one argument, it returns that argument. + +@smallexample +@group + ; @r{ 24-bit binary values} + +(logand 14 13) ; 14 = @r{0000 0000 0000 0000 0000 1110} + ; 13 = @r{0000 0000 0000 0000 0000 1101} + @result{} 12 ; 12 = @r{0000 0000 0000 0000 0000 1100} +@end group + +@group +(logand 14 13 4) ; 14 = @r{0000 0000 0000 0000 0000 1110} + ; 13 = @r{0000 0000 0000 0000 0000 1101} + ; 4 = @r{0000 0000 0000 0000 0000 0100} + @result{} 4 ; 4 = @r{0000 0000 0000 0000 0000 0100} +@end group + +@group +(logand) + @result{} -1 ; -1 = @r{1111 1111 1111 1111 1111 1111} +@end group +@end smallexample +@end defun + +@defun logior &rest ints-or-markers +@cindex logical inclusive or +@cindex bitwise or +This function returns the ``inclusive or'' of its arguments: the @var{n}th bit +is set in the result if, and only if, the @var{n}th bit is set in at least +one of the arguments. If there are no arguments, the result is zero, +which is an identity element for this operation. If @code{logior} is +passed just one argument, it returns that argument. + +@smallexample +@group + ; @r{ 24-bit binary values} + +(logior 12 5) ; 12 = @r{0000 0000 0000 0000 0000 1100} + ; 5 = @r{0000 0000 0000 0000 0000 0101} + @result{} 13 ; 13 = @r{0000 0000 0000 0000 0000 1101} +@end group + +@group +(logior 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 1100} + ; 5 = @r{0000 0000 0000 0000 0000 0101} + ; 7 = @r{0000 0000 0000 0000 0000 0111} + @result{} 15 ; 15 = @r{0000 0000 0000 0000 0000 1111} +@end group +@end smallexample +@end defun + +@defun logxor &rest ints-or-markers +@cindex bitwise exclusive or +@cindex logical exclusive or +This function returns the ``exclusive or'' of its arguments: the +@var{n}th bit is set in the result if, and only if, the @var{n}th bit +is set in an odd number of the arguments. If there are no arguments, +the result is 0. If @code{logxor} is passed just one argument, it returns +that argument. + +@smallexample +@group + ; @r{ 24-bit binary values} + +(logxor 12 5) ; 12 = @r{0000 0000 0000 0000 0000 1100} + ; 5 = @r{0000 0000 0000 0000 0000 0101} + @result{} 9 ; 9 = @r{0000 0000 0000 0000 0000 1001} +@end group + +@group +(logxor 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 1100} + ; 5 = @r{0000 0000 0000 0000 0000 0101} + ; 7 = @r{0000 0000 0000 0000 0000 0111} + @result{} 14 ; 14 = @r{0000 0000 0000 0000 0000 1110} +@end group +@end smallexample +@end defun + +@defun lognot integer +@cindex logical not +@cindex bitwise not +This function returns the logical complement of its argument: the @var{n}th +bit is one in the result if, and only if, the @var{n}th bit is zero in +@var{integer}, and vice-versa. + +@example +(lognot 5) + @result{} -6 +;; 5 = @r{0000 0000 0000 0000 0000 0101} +;; @r{becomes} +;; -6 = @r{1111 1111 1111 1111 1111 1010} +@end example +@end defun + +@node Transcendental Functions +@section Transcendental Functions +@cindex transcendental functions +@cindex mathematical functions + +These mathematical functions are available if floating point is +supported. They allow integers as well as floating point numbers +as arguments. + +@defun sin arg +@defunx cos arg +@defunx tan arg +These are the ordinary trigonometric functions, with argument measured +in radians. +@end defun + +@defun asin arg +The value of @code{(asin @var{arg})} is a number between @minus{} pi / 2 +and pi / 2 (inclusive) whose sine is @var{arg}; if, however, @var{arg} +is out of range (outside [-1, 1]), then the result is a NaN. +@end defun + +@defun acos arg +The value of @code{(acos @var{arg})} is a number between 0 and pi +(inclusive) whose cosine is @var{arg}; if, however, @var{arg} +is out of range (outside [-1, 1]), then the result is a NaN. +@end defun + +@defun atan arg +The value of @code{(atan @var{arg})} is a number between @minus{} pi / 2 +and pi / 2 (exclusive) whose tangent is @var{arg}. +@end defun + +@defun exp arg +This is the exponential function; it returns @i{e} to the power +@var{arg}. @i{e} is a fundamental mathematical constant also called the +base of natural logarithms. +@end defun + +@defun log arg &optional base +This function returns the logarithm of @var{arg}, with base @var{base}. +If you don't specify @var{base}, the base @var{e} is used. If @var{arg} +is negative, the result is a NaN. +@end defun + +@ignore +@defun expm1 arg +This function returns @code{(1- (exp @var{arg}))}, but it is more +accurate than that when @var{arg} is negative and @code{(exp @var{arg})} +is close to 1. +@end defun + +@defun log1p arg +This function returns @code{(log (1+ @var{arg}))}, but it is more +accurate than that when @var{arg} is so small that adding 1 to it would +lose accuracy. +@end defun +@end ignore + +@defun log10 arg +This function returns the logarithm of @var{arg}, with base 10. If +@var{arg} is negative, the result is a NaN. +@end defun + +@defun expt x y +This function returns @var{x} raised to power @var{y}. +@end defun + +@defun sqrt arg +This returns the square root of @var{arg}. If @var{arg} is negative, +the value is a NaN. +@end defun + +@node Random Numbers +@section Random Numbers +@cindex random numbers + +A deterministic computer program cannot generate true random numbers. +For most purposes, @dfn{pseudo-random numbers} suffice. A series of +pseudo-random numbers is generated in a deterministic fashion. The +numbers are not truly random, but they have certain properties that +mimic a random series. For example, all possible values occur equally +often in a pseudo-random series. + +In Emacs, pseudo-random numbers are generated from a ``seed'' number. +Starting from any given seed, the @code{random} function always +generates the same sequence of numbers. Emacs always starts with the +same seed value, so the sequence of values of @code{random} is actually +the same in each Emacs run! For example, in one operating system, the +first call to @code{(random)} after you start Emacs always returns +-1457731, and the second one always returns -7692030. This +repeatability is helpful for debugging. + +If you want truly unpredictable random numbers, execute @code{(random +t)}. This chooses a new seed based on the current time of day and on +Emacs's process @sc{id} number. + +@defun random &optional limit +This function returns a pseudo-random integer. Repeated calls return a +series of pseudo-random integers. + +If @var{limit} is @code{nil}, then the value may in principle be any +integer. If @var{limit} is a positive integer, the value is chosen to +be nonnegative and less than @var{limit} (only in Emacs 19). + +If @var{limit} is @code{t}, it means to choose a new seed based on the +current time of day and on Emacs's process @sc{id} number. +@c "Emacs'" is incorrect usage! + +On some machines, any integer representable in Lisp may be the result +of @code{random}. On other machines, the result can never be larger +than a certain maximum or less than a certain (negative) minimum. +@end defun
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/variables.texi Thu Mar 24 17:24:15 1994 +0000 @@ -0,0 +1,1262 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/variables +@node Variables, Functions, Control Structures, Top +@chapter Variables +@cindex variable + + A @dfn{variable} is a name used in a program to stand for a value. +Nearly all programming languages have variables of some sort. In the +text of a Lisp program, variables are written using the syntax for +symbols. + + In Lisp, unlike most programming languages, programs are represented +primarily as Lisp objects and only secondarily as text. The Lisp +objects used for variables are symbols: the symbol name is the variable +name, and the variable's value is stored in the value cell of the +symbol. The use of a symbol as a variable is independent of its use as +a function name. @xref{Symbol Components}. + + The Lisp objects that constitute a Lisp program determine the textual +form of the program--it is simply the read syntax for those Lisp +objects. This is why, for example, a variable in a textual Lisp program +is written using the read syntax for the symbol that represents the +variable. + +@menu +* Global Variables:: Variable values that exist permanently, everywhere. +* Constant Variables:: Certain "variables" have values that never change. +* Local Variables:: Variable values that exist only temporarily. +* Void Variables:: Symbols that lack values. +* Defining Variables:: A definition says a symbol is used as a variable. +* Accessing Variables:: Examining values of variables whose names + are known only at run time. +* Setting Variables:: Storing new values in variables. +* Variable Scoping:: How Lisp chooses among local and global values. +* Buffer-Local Variables:: Variable values in effect only in one buffer. +@end menu + +@node Global Variables +@section Global Variables +@cindex global variable + + The simplest way to use a variable is @dfn{globally}. This means that +the variable has just one value at a time, and this value is in effect +(at least for the moment) throughout the Lisp system. The value remains +in effect until you specify a new one. When a new value replaces the +old one, no trace of the old value remains in the variable. + + You specify a value for a symbol with @code{setq}. For example, + +@example +(setq x '(a b)) +@end example + +@noindent +gives the variable @code{x} the value @code{(a b)}. Note that +@code{setq} does not evaluate its first argument, the name of the +variable, but it does evaluate the second argument, the new value. + + Once the variable has a value, you can refer to it by using the symbol +by itself as an expression. Thus, + +@example +@group +x @result{} (a b) +@end group +@end example + +@noindent +assuming the @code{setq} form shown above has already been executed. + + If you do another @code{setq}, the new value replaces the old one: + +@example +@group +x + @result{} (a b) +@end group +@group +(setq x 4) + @result{} 4 +@end group +@group +x + @result{} 4 +@end group +@end example + +@node Constant Variables +@section Variables That Never Change +@vindex nil +@vindex t +@kindex setting-constant + + Emacs Lisp has two special symbols, @code{nil} and @code{t}, that +always evaluate to themselves. These symbols cannot be rebound, nor can +their value cells be changed. An attempt to change the value of +@code{nil} or @code{t} signals a @code{setting-constant} error. + +@example +@group +nil @equiv{} 'nil + @result{} nil +@end group +@group +(setq nil 500) +@error{} Attempt to set constant symbol: nil +@end group +@end example + +@node Local Variables +@section Local Variables +@cindex binding local variables +@cindex local variables +@cindex local binding +@cindex global binding + + Global variables have values that last until explicitly superseded +with new values. Sometimes it is useful to create variable values that +exist temporarily---only while within a certain part of the program. +These values are called @dfn{local}, and the variables so used are +called @dfn{local variables}. + + For example, when a function is called, its argument variables receive +new local values that last until the function exits. The @code{let} +special form explicitly establishes new local values for specified +variables; these last until exit from the @code{let} form. + +@cindex shadowing of variables + Establishing a local value saves away the previous value (or lack of +one) of the variable. When the life span of the local value is over, +the previous value is restored. In the mean time, we say that the +previous value is @dfn{shadowed} and @dfn{not visible}. Both global and +local values may be shadowed (@pxref{Scope}). + + If you set a variable (such as with @code{setq}) while it is local, +this replaces the local value; it does not alter the global value, or +previous local values that are shadowed. To model this behavior, we +speak of a @dfn{local binding} of the variable as well as a local value. + + The local binding is a conceptual place that holds a local value. +Entry to a function, or a special form such as @code{let}, creates the +local binding; exit from the function or from the @code{let} removes the +local binding. As long as the local binding lasts, the variable's value +is stored within it. Use of @code{setq} or @code{set} while there is a +local binding stores a different value into the local binding; it does +not create a new binding. + + We also speak of the @dfn{global binding}, which is where +(conceptually) the global value is kept. + +@cindex current binding + A variable can have more than one local binding at a time (for +example, if there are nested @code{let} forms that bind it). In such a +case, the most recently created local binding that still exists is the +@dfn{current binding} of the variable. (This is called @dfn{dynamic +scoping}; see @ref{Variable Scoping}.) If there are no local bindings, +the variable's global binding is its current binding. We also call the +current binding the @dfn{most-local existing binding}, for emphasis. +Ordinary evaluation of a symbol always returns the value of its current +binding. + + The special forms @code{let} and @code{let*} exist to create +local bindings. + +@defspec let (bindings@dots{}) forms@dots{} +This function binds variables according to @var{bindings} and then +evaluates all of the @var{forms} in textual order. The @code{let}-form +returns the value of the last form in @var{forms}. + +Each of the @var{bindings} is either @w{(i) a} symbol, in which case +that symbol is bound to @code{nil}; or @w{(ii) a} list of the form +@code{(@var{symbol} @var{value-form})}, in which case @var{symbol} is +bound to the result of evaluating @var{value-form}. If @var{value-form} +is omitted, @code{nil} is used. + +All of the @var{value-form}s in @var{bindings} are evaluated in the +order they appear and @emph{before} any of the symbols are bound. Here +is an example of this: @code{Z} is bound to the old value of @code{Y}, +which is 2, not the new value, 1. + +@example +@group +(setq Y 2) + @result{} 2 +@end group +@group +(let ((Y 1) + (Z Y)) + (list Y Z)) + @result{} (1 2) +@end group +@end example +@end defspec + +@defspec let* (bindings@dots{}) forms@dots{} +This special form is like @code{let}, but it binds each variable right +after computing its local value, before computing the local value for +the next variable. Therefore, an expression in @var{bindings} can +reasonably refer to the preceding symbols bound in this @code{let*} +form. Compare the following example with the example above for +@code{let}. + +@example +@group +(setq Y 2) + @result{} 2 +@end group +@group +(let* ((Y 1) + (Z Y)) ; @r{Use the just-established value of @code{Y}.} + (list Y Z)) + @result{} (1 1) +@end group +@end example +@end defspec + + Here is a complete list of the other facilities which create local +bindings: + +@itemize @bullet +@item +Function calls (@pxref{Functions}). + +@item +Macro calls (@pxref{Macros}). + +@item +@code{condition-case} (@pxref{Errors}). +@end itemize + +@defvar max-specpdl-size +@cindex variable limit error +@cindex evaluation error +@cindex infinite recursion + This variable defines the limit on the total number of local variable +bindings and @code{unwind-protect} cleanups (@pxref{Nonlocal Exits}) +that are allowed before signaling an error (with data @code{"Variable +binding depth exceeds max-specpdl-size"}). + + This limit, with the associated error when it is exceeded, is one way +that Lisp avoids infinite recursion on an ill-defined function. + + The default value is 600. + + @code{max-lisp-eval-depth} provides another limit on depth of nesting. +@xref{Eval}. +@end defvar + +@node Void Variables +@section When a Variable is ``Void'' +@kindex void-variable +@cindex void variable + + If you have never given a symbol any value as a global variable, we +say that that symbol's global value is @dfn{void}. In other words, the +symbol's value cell does not have any Lisp object in it. If you try to +evaluate the symbol, you get a @code{void-variable} error rather than +a value. + + Note that a value of @code{nil} is not the same as void. The symbol +@code{nil} is a Lisp object and can be the value of a variable just as any +other object can be; but it is @emph{a value}. A void variable does not +have any value. + + After you have given a variable a value, you can make it void once more +using @code{makunbound}. + +@defun makunbound symbol +This function makes the current binding of @var{symbol} void. +Subsequent attempts to use this symbol's value as a variable will signal +the error @code{void-variable}, unless or until you set it again. + +@code{makunbound} returns @var{symbol}. + +@example +@group +(makunbound 'x) ; @r{Make the global value} + ; @r{of @code{x} void.} + @result{} x +@end group +@group +x +@error{} Symbol's value as variable is void: x +@end group +@end example + +If @var{symbol} is locally bound, @code{makunbound} affects the most +local existing binding. This is the only way a symbol can have a void +local binding, since all the constructs that create local bindings +create them with values. In this case, the voidness lasts at most as +long as the binding does; when the binding is removed due to exit from +the construct that made it, the previous or global binding is reexposed +as usual, and the variable is no longer void unless the newly reexposed +binding was void all along. + +@smallexample +@group +(setq x 1) ; @r{Put a value in the global binding.} + @result{} 1 +(let ((x 2)) ; @r{Locally bind it.} + (makunbound 'x) ; @r{Void the local binding.} + x) +@error{} Symbol's value as variable is void: x +@end group +@group +x ; @r{The global binding is unchanged.} + @result{} 1 + +(let ((x 2)) ; @r{Locally bind it.} + (let ((x 3)) ; @r{And again.} + (makunbound 'x) ; @r{Void the innermost-local binding.} + x)) ; @r{And refer: it's void.} +@error{} Symbol's value as variable is void: x +@end group + +@group +(let ((x 2)) + (let ((x 3)) + (makunbound 'x)) ; @r{Void inner binding, then remove it.} + x) ; @r{Now outer @code{let} binding is visible.} + @result{} 2 +@end group +@end smallexample +@end defun + + A variable that has been made void with @code{makunbound} is +indistinguishable from one that has never received a value and has +always been void. + + You can use the function @code{boundp} to test whether a variable is +currently void. + +@defun boundp variable +@code{boundp} returns @code{t} if @var{variable} (a symbol) is not void; +more precisely, if its current binding is not void. It returns +@code{nil} otherwise. + +@smallexample +@group +(boundp 'abracadabra) ; @r{Starts out void.} + @result{} nil +@end group +@group +(let ((abracadabra 5)) ; @r{Locally bind it.} + (boundp 'abracadabra)) + @result{} t +@end group +@group +(boundp 'abracadabra) ; @r{Still globally void.} + @result{} nil +@end group +@group +(setq abracadabra 5) ; @r{Make it globally nonvoid.} + @result{} 5 +@end group +@group +(boundp 'abracadabra) + @result{} t +@end group +@end smallexample +@end defun + +@node Defining Variables +@section Defining Global Variables + + You may announce your intention to use a symbol as a global variable +with a definition, using @code{defconst} or @code{defvar}. + + In Emacs Lisp, definitions serve three purposes. First, they inform +people who read the code that certain symbols are @emph{intended} to be +used a certain way (as variables). Second, they inform the Lisp system +of these things, supplying a value and documentation. Third, they +provide information to utilities such as @code{etags} and +@code{make-docfile}, which create data bases of the functions and +variables in a program. + + The difference between @code{defconst} and @code{defvar} is primarily +a matter of intent, serving to inform human readers of whether programs +will change the variable. Emacs Lisp does not restrict the ways in +which a variable can be used based on @code{defconst} or @code{defvar} +declarations. However, it also makes a difference for initialization: +@code{defconst} unconditionally initializes the variable, while +@code{defvar} initializes it only if it is void. + + One would expect user option variables to be defined with +@code{defconst}, since programs do not change them. Unfortunately, this +has bad results if the definition is in a library that is not preloaded: +@code{defconst} would override any prior value when the library is +loaded. Users would like to be able to set user options in their init +files, and override the default values given in the definitions. For +this reason, user options must be defined with @code{defvar}. + +@defspec defvar symbol [value [doc-string]] +This special form defines @var{symbol} as a value and initializes it. +The definition informs a person reading your code that @var{symbol} is +used as a variable that programs are likely to set or change. It is +also used for all user option variables except in the preloaded parts of +Emacs. Note that @var{symbol} is not evaluated; the symbol to be +defined must appear explicitly in the @code{defvar}. + +If @var{symbol} already has a value (i.e., it is not void), @var{value} +is not even evaluated, and @var{symbol}'s value remains unchanged. If +@var{symbol} is void and @var{value} is specified, @code{defvar} +evaluates it and sets @var{symbol} to the result. (If @var{value} is +omitted, the value of @var{symbol} is not changed in any case.) + +If @var{symbol} has a buffer-local binding in the current buffer, +@code{defvar} sets the default value, not the local value. +@xref{Buffer-Local Variables}. + +If the @var{doc-string} argument appears, it specifies the documentation +for the variable. (This opportunity to specify documentation is one of +the main benefits of defining the variable.) The documentation is +stored in the symbol's @code{variable-documentation} property. The +Emacs help functions (@pxref{Documentation}) look for this property. + +If the first character of @var{doc-string} is @samp{*}, it means that +this variable is considered a user option. This lets users set the +variable conventiently using the commands @code{set-variable} and +@code{edit-options}. + +For example, this form defines @code{foo} but does not set its value: + +@example +@group +(defvar foo) + @result{} foo +@end group +@end example + +The following example sets the value of @code{bar} to @code{23}, and +gives it a documentation string: + +@example +@group +(defvar bar 23 + "The normal weight of a bar.") + @result{} bar +@end group +@end example + +The following form changes the documentation string for @code{bar}, +making it a user option, but does not change the value, since @code{bar} +already has a value. (The addition @code{(1+ 23)} is not even +performed.) + +@example +@group +(defvar bar (1+ 23) + "*The normal weight of a bar.") + @result{} bar +@end group +@group +bar + @result{} 23 +@end group +@end example + +Here is an equivalent expression for the @code{defvar} special form: + +@example +@group +(defvar @var{symbol} @var{value} @var{doc-string}) +@equiv{} +(progn + (if (not (boundp '@var{symbol})) + (setq @var{symbol} @var{value})) + (put '@var{symbol} 'variable-documentation '@var{doc-string}) + '@var{symbol}) +@end group +@end example + +The @code{defvar} form returns @var{symbol}, but it is normally used +at top level in a file where its value does not matter. +@end defspec + +@defspec defconst symbol [value [doc-string]] +This special form defines @var{symbol} as a value and initializes it. +It informs a person reading your code that @var{symbol} has a global +value, established here, that will not normally be changed or locally +bound by the execution of the program. The user, however, may be +welcome to change it. Note that @var{symbol} is not evaluated; the +symbol to be defined must appear explicitly in the @code{defconst}. + +@code{defconst} always evaluates @var{value} and sets the global value +of @var{symbol} to the result, provided @var{value} is given. If +@var{symbol} has a buffer-local binding in the current buffer, +@code{defconst} sets the default value, not the local value. + +@strong{Please note:} don't use @code{defconst} for user option +variables in libraries that are not standardly preloaded. The user +should be able to specify a value for such a variable in the +@file{.emacs} file, so that it will be in effect if and when the library +is loaded later. + +Here, @code{pi} is a constant that presumably ought not to be changed +by anyone (attempts by the Indiana State Legislature notwithstanding). +As the second form illustrates, however, this is only advisory. + +@example +@group +(defconst pi 3.1415 "Pi to five places.") + @result{} pi +@end group +@group +(setq pi 3) + @result{} pi +@end group +@group +pi + @result{} 3 +@end group +@end example +@end defspec + +@defun user-variable-p variable +@cindex user option +This function returns @code{t} if @var{variable} is a user option--- a +variable intended to be set by the user for customization---and +@code{nil} otherwise. (Variables other than user options exist for the +internal purposes of Lisp programs, and users need not know about them.) + +User option variables are distinguished from other variables by the +first character of the @code{variable-documentation} property. If the +property exists and is a string, and its first character is @samp{*}, +then the variable is a user option. +@end defun + + If a user option variable has a @code{variable-interactive} property, +@code{set-variable} uses that value to control reading the new value for +the variable. The property's value is used as if it were the argument +to @code{interactive}. + + @strong{Warning:} if the @code{defconst} and @code{defvar} special +forms are used while the variable has a local binding, they set the +local binding's value; the global binding is not changed. This is not +what we really want. To prevent it, use these special forms at top +level in a file, where normally no local binding is in effect, and make +sure to load the file before making a local binding for the variable. + +@node Accessing Variables +@section Accessing Variable Values + + The usual way to reference a variable is to write the symbol which +names it (@pxref{Symbol Forms}). This requires you to specify the +variable name when you write the program. Usually that is exactly what +you want to do. Occasionally you need to choose at run time which +variable to reference; then you can use @code{symbol-value}. + +@defun symbol-value symbol +This function returns the value of @var{symbol}. This is the value in +the innermost local binding of the symbol, or its global value if it +has no local bindings. + +@example +@group +(setq abracadabra 5) + @result{} 5 +@end group +@group +(setq foo 9) + @result{} 9 +@end group + +@group +;; @r{Here the symbol @code{abracadabra}} +;; @r{is the symbol whose value is examined.} +(let ((abracadabra 'foo)) + (symbol-value 'abracadabra)) + @result{} foo +@end group + +@group +;; @r{Here the value of @code{abracadabra},} +;; @r{which is @code{foo},} +;; @r{is the symbol whose value is examined.} +(let ((abracadabra 'foo)) + (symbol-value abracadabra)) + @result{} 9 +@end group + +@group +(symbol-value 'abracadabra) + @result{} 5 +@end group +@end example + +A @code{void-variable} error is signaled if @var{symbol} has neither a +local binding nor a global value. +@end defun + +@node Setting Variables +@section How to Alter a Variable Value + + The usual way to change the value of a variable is with the special +form @code{setq}. When you need to compute the choice of variable at +run time, use the function @code{set}. + +@defspec setq [symbol form]@dots{} +This special form is the most common method of changing a variable's +value. Each @var{symbol} is given a new value, which is the result of +evaluating the corresponding @var{form}. The most-local existing +binding of the symbol is changed. + +@code{setq} does not evaluate @var{symbol}; it sets the symbol that you +write. We say that this argument is @dfn{automatically quoted}. The +@samp{q} in @code{setq} stands for ``quoted.'' + +The value of the @code{setq} form is the value of the last @var{form}. + +@example +@group +(setq x (1+ 2)) + @result{} 3 +@end group +x ; @r{@code{x} now has a global value.} + @result{} 3 +@group +(let ((x 5)) + (setq x 6) ; @r{The local binding of @code{x} is set.} + x) + @result{} 6 +@end group +x ; @r{The global value is unchanged.} + @result{} 3 +@end example + +Note that the first @var{form} is evaluated, then the first +@var{symbol} is set, then the second @var{form} is evaluated, then the +second @var{symbol} is set, and so on: + +@example +@group +(setq x 10 ; @r{Notice that @code{x} is set before} + y (1+ x)) ; @r{the value of @code{y} is computed.} + @result{} 11 +@end group +@end example +@end defspec + +@defun set symbol value +This function sets @var{symbol}'s value to @var{value}, then returns +@var{value}. Since @code{set} is a function, the expression written for +@var{symbol} is evaluated to obtain the symbol to set. + +The most-local existing binding of the variable is the binding that is +set; shadowed bindings are not affected. If @var{symbol} is not +actually a symbol, a @code{wrong-type-argument} error is signaled. + +@example +@group +(set one 1) +@error{} Symbol's value as variable is void: one +@end group +@group +(set 'one 1) + @result{} 1 +@end group +@group +(set 'two 'one) + @result{} one +@end group +@group +(set two 2) ; @r{@code{two} evaluates to symbol @code{one}.} + @result{} 2 +@end group +@group +one ; @r{So it is @code{one} that was set.} + @result{} 2 +(let ((one 1)) ; @r{This binding of @code{one} is set,} + (set 'one 3) ; @r{not the global value.} + one) + @result{} 3 +@end group +@group +one + @result{} 2 +@end group +@end example + +Logically speaking, @code{set} is a more fundamental primitive than +@code{setq}. Any use of @code{setq} can be trivially rewritten to use +@code{set}; @code{setq} could even be defined as a macro, given the +availability of @code{set}. However, @code{set} itself is rarely used; +beginners hardly need to know about it. It is needed for choosing which +variable to set is made at run time. For example, the command +@code{set-variable}, which reads a variable name from the user and then +sets the variable, needs to use @code{set}. + +@cindex CL note---@code{set} local +@quotation +@b{Common Lisp note:} in Common Lisp, @code{set} always changes the +symbol's special value, ignoring any lexical bindings. In Emacs Lisp, +all variables and all bindings are (in effect) special, so @code{set} +always affects the most local existing binding. +@end quotation +@end defun + +@node Variable Scoping +@section Scoping Rules for Variable Bindings + + A given symbol @code{foo} may have several local variable bindings, +established at different places in the Lisp program, as well as a global +binding. The most recently established binding takes precedence over +the others. + +@cindex scope +@cindex extent +@cindex dynamic scoping + Local bindings in Emacs Lisp have @dfn{indefinite scope} and +@dfn{dynamic extent}. @dfn{Scope} refers to @emph{where} textually in +the source code the binding can be accessed. Indefinite scope means +that any part of the program can potentially access the variable +binding. @dfn{Extent} refers to @emph{when}, as the program is +executing, the binding exists. Dynamic extent means that the binding +lasts as long as the activation of the construct that established it. + + The combination of dynamic extent and indefinite scope is called +@dfn{dynamic scoping}. By contrast, most programming languages use +@dfn{lexical scoping}, in which references to a local variable must be +located textually within the function or block that binds the variable. + +@cindex CL note---special variables +@quotation +@b{Common Lisp note:} variables declared ``special'' in Common Lisp +are dynamically scoped like variables in Emacs Lisp. +@end quotation + +@menu +* Scope:: Scope means where in the program a value is visible. + Comparison with other languages. +* Extent:: Extent means how long in time a value exists. +* Impl of Scope:: Two ways to implement dynamic scoping. +* Using Scoping:: How to use dynamic scoping carefully and avoid problems. +@end menu + +@node Scope +@subsection Scope + + Emacs Lisp uses @dfn{indefinite scope} for local variable bindings. +This means that any function anywhere in the program text might access a +given binding of a variable. Consider the following function +definitions: + +@example +@group +(defun binder (x) ; @r{@code{x} is bound in @code{binder}.} + (foo 5)) ; @r{@code{foo} is some other function.} +@end group + +@group +(defun user () ; @r{@code{x} is used in @code{user}.} + (list x)) +@end group +@end example + + In a lexically scoped language, the binding of @code{x} in +@code{binder} would never be accessible in @code{user}, because +@code{user} is not textually contained within the function +@code{binder}. However, in dynamically scoped Emacs Lisp, @code{user} +may or may not refer to the binding of @code{x} established in +@code{binder}, depending on circumstances: + +@itemize @bullet +@item +If we call @code{user} directly without calling @code{binder} at all, +then whatever binding of @code{x} is found, it cannot come from +@code{binder}. + +@item +If we define @code{foo} as follows and call @code{binder}, then the +binding made in @code{binder} will be seen in @code{user}: + +@example +@group +(defun foo (lose) + (user)) +@end group +@end example + +@item +If we define @code{foo} as follows and call @code{binder}, then the +binding made in @code{binder} @emph{will not} be seen in @code{user}: + +@example +(defun foo (x) + (user)) +@end example + +@noindent +Here, when @code{foo} is called by @code{binder}, it binds @code{x}. +(The binding in @code{foo} is said to @dfn{shadow} the one made in +@code{binder}.) Therefore, @code{user} will access the @code{x} bound +by @code{foo} instead of the one bound by @code{binder}. +@end itemize + +@node Extent +@subsection Extent + + @dfn{Extent} refers to the time during program execution that a +variable name is valid. In Emacs Lisp, a variable is valid only while +the form that bound it is executing. This is called @dfn{dynamic +extent}. ``Local'' or ``automatic'' variables in most languages, +including C and Pascal, have dynamic extent. + + One alternative to dynamic extent is @dfn{indefinite extent}. This +means that a variable binding can live on past the exit from the form +that made the binding. Common Lisp and Scheme, for example, support +this, but Emacs Lisp does not. + + To illustrate this, the function below, @code{make-add}, returns a +function that purports to add @var{n} to its own argument @var{m}. +This would work in Common Lisp, but it does not work as intended in +Emacs Lisp, because after the call to @code{make-add} exits, the +variable @code{n} is no longer bound to the actual argument 2. + +@example +(defun make-add (n) + (function (lambda (m) (+ n m)))) ; @r{Return a function.} + @result{} make-add +(fset 'add2 (make-add 2)) ; @r{Define function @code{add2}} + ; @r{with @code{(make-add 2)}.} + @result{} (lambda (m) (+ n m)) +(add2 4) ; @r{Try to add 2 to 4.} +@error{} Symbol's value as variable is void: n +@end example + +@cindex closures not available + Some Lisp dialects have ``closures'', objects that are like functions +but record additional variable bindings. Emacs Lisp does not have +closures. + +@node Impl of Scope +@subsection Implementation of Dynamic Scoping +@cindex deep binding + + A simple sample implementation (which is not how Emacs Lisp actually +works) may help you understand dynamic binding. This technique is +called @dfn{deep binding} and was used in early Lisp systems. + + Suppose there is a stack of bindings: variable-value pairs. At entry +to a function or to a @code{let} form, we can push bindings on the stack +for the arguments or local variables created there. We can pop those +bindings from the stack at exit from the binding construct. + + We can find the value of a variable by searching the stack from top to +bottom for a binding for that variable; the value from that binding is +the value of the variable. To set the variable, we search for the +current binding, then store the new value into that binding. + + As you can see, a function's bindings remain in effect as long as it +continues execution, even during its calls to other functions. That is +why we say the extent of the binding is dynamic. And any other function +can refer to the bindings, if it uses the same variables while the +bindings are in effect. That is why we say the scope is indefinite. + +@cindex shallow binding + The actual implementation of variable scoping in GNU Emacs Lisp uses a +technique called @dfn{shallow binding}. Each variable has a standard +place in which its current value is always found---the value cell of the +symbol. + + In shallow binding, setting the variable works by storing a value in +the value cell. Creating a new binding works by pushing the old value +(belonging to a previous binding) on a stack, and storing the local value +in the value cell. Eliminating a binding works by popping the old value +off the stack, into the value cell. + + We use shallow binding because it has the same results as deep +binding, but runs faster, since there is never a need to search for a +binding. + +@node Using Scoping +@subsection Proper Use of Dynamic Scoping + + Binding a variable in one function and using it in another is a +powerful technique, but if used without restraint, it can make programs +hard to understand. There are two clean ways to use this technique: + +@itemize @bullet +@item +Use or bind the variable only in a few related functions, written close +together in one file. Such a variable is used for communication within +one program. + +You should write comments to inform other programmers that they can see +all uses of the variable before them, and to advise them not to add uses +elsewhere. + +@item +Give the variable a well-defined, documented meaning, and make all +appropriate functions refer to it (but not bind it or set it) wherever +that meaning is relevant. For example, the variable +@code{case-fold-search} is defined as ``non-@code{nil} means ignore case +when searching''; various search and replace functions refer to it +directly or through their subroutines, but do not bind or set it. + +Then you can bind the variable in other programs, knowing reliably what +the effect will be. +@end itemize + +@node Buffer-Local Variables +@section Buffer-Local Variables +@cindex variables, buffer-local +@cindex buffer-local variables + + Global and local variable bindings are found in most programming +languages in one form or another. Emacs also supports another, unusual +kind of variable binding: @dfn{buffer-local} bindings, which apply only +to one buffer. Emacs Lisp is meant for programming editing commands, +and having different values for a variable in different buffers is an +important customization method. + +@menu +* Intro to Buffer-Local:: Introduction and concepts. +* Creating Buffer-Local:: Creating and destroying buffer-local bindings. +* Default Value:: The default value is seen in buffers + that don't have their own local values. +@end menu + +@node Intro to Buffer-Local +@subsection Introduction to Buffer-Local Variables + + A buffer-local variable has a buffer-local binding associated with a +particular buffer. The binding is in effect when that buffer is +current; otherwise, it is not in effect. If you set the variable while +a buffer-local binding is in effect, the new value goes in that binding, +so the global binding is unchanged; this means that the change is +visible in that buffer alone. + + A variable may have buffer-local bindings in some buffers but not in +others. The global binding is shared by all the buffers that don't have +their own bindings. Thus, if you set the variable in a buffer that does +not have a buffer-local binding for it, the new value is visible in all +buffers except those with buffer-local bindings. (Here we are assuming +that there are no @code{let}-style local bindings to complicate the issue.) + + The most common use of buffer-local bindings is for major modes to change +variables that control the behavior of commands. For example, C mode and +Lisp mode both set the variable @code{paragraph-start} to specify that only +blank lines separate paragraphs. They do this by making the variable +buffer-local in the buffer that is being put into C mode or Lisp mode, and +then setting it to the new value for that mode. + + The usual way to make a buffer-local binding is with +@code{make-local-variable}, which is what major mode commands use. This +affects just the current buffer; all other buffers (including those yet to +be created) continue to share the global value. + +@cindex automatically buffer-local + A more powerful operation is to mark the variable as +@dfn{automatically buffer-local} by calling +@code{make-variable-buffer-local}. You can think of this as making the +variable local in all buffers, even those yet to be created. More +precisely, the effect is that setting the variable automatically makes +the variable local to the current buffer if it is not already so. All +buffers start out by sharing the global value of the variable as usual, +but any @code{setq} creates a buffer-local binding for the current +buffer. The new value is stored in the buffer-local binding, leaving +the (default) global binding untouched. The global value can no longer +be changed with @code{setq}; you need to use @code{setq-default} to do +that. + + @strong{Warning:} when a variable has local values in one or more +buffers, you can get Emacs very confused by binding the variable with +@code{let}, changing to a different current buffer in which a different +binding is in effect, and then exiting the @code{let}. This can +scramble the values of the global and local bindings. + + To preserve your sanity, avoid that series of actions. If you use +@code{save-excursion} around each piece of code that changes to a +different current buffer, you will not have this problem. Here is an +example of what to avoid: + +@example +@group +(setq foo 'b) +(set-buffer "a") +(make-local-variable 'foo) +@end group +(setq foo 'a) +(let ((foo 'temp)) + (set-buffer "b") + @dots{}) +@group +foo @result{} 'a ; @r{The old buffer-local value from buffer @samp{a}} + ; @r{is now the default value.} +@end group +@group +(set-buffer "a") +foo @result{} 'temp ; @r{The local value that should be gone} + ; @r{is now the buffer-local value in buffer @samp{a}.} +@end group +@end example + +@noindent +But @code{save-excursion} as shown here avoids the problem: + +@example +@group +(let ((foo 'temp)) + (save-excursion + (set-buffer "b") + @var{body}@dots{})) +@end group +@end example + + Note that references to @code{foo} in @var{body} access the +buffer-local binding of buffer @samp{b}. + + When a file specifies local variable values, these become buffer-local +value when you visit the file. @xref{Auto Major Mode}. + +@node Creating Buffer-Local +@subsection Creating and Deleting Buffer-Local Bindings + +@deffn Command make-local-variable variable +This function creates a buffer-local binding in the current buffer for +@var{variable} (a symbol). Other buffers are not affected. The value +returned is @var{variable}. + +@c Emacs 19 feature +The buffer-local value of @var{variable} starts out as the same value +@var{variable} previously had. If @var{variable} was void, it remains +void. + +@example +@group +;; @r{In buffer @samp{b1}:} +(setq foo 5) ; @r{Affects all buffers.} + @result{} 5 +@end group +@group +(make-local-variable 'foo) ; @r{Now it is local in @samp{b1}.} + @result{} foo +@end group +@group +foo ; @r{That did not change} + @result{} 5 ; @r{the value.} +@end group +@group +(setq foo 6) ; @r{Change the value} + @result{} 6 ; @r{in @samp{b1}.} +@end group +@group +foo + @result{} 6 +@end group + +@group +;; @r{In buffer @samp{b2}, the value hasn't changed.} +(save-excursion + (set-buffer "b2") + foo) + @result{} 5 +@end group +@end example +@end deffn + +@deffn Command make-variable-buffer-local variable +This function marks @var{variable} (a symbol) automatically +buffer-local, so that any subsequent attempt to set it will make it +local to the current buffer at the time. + +The value returned is @var{variable}. +@end deffn + +@defun buffer-local-variables &optional buffer +This function returns a list describing the buffer-local variables in +buffer @var{buffer}. It returns an association list (@pxref{Association +Lists}) in which each association contains one buffer-local variable and +its value. When a buffer-local variable is void in @var{buffer}, then +it appears directly in the resulting list. If @var{buffer} is omitted, +the current buffer is used. + +@example +@group +(make-local-variable 'foobar) +(makunbound 'foobar) +(make-local-variable 'bind-me) +(setq bind-me 69) +@end group +(setq lcl (buffer-local-variables)) + ;; @r{First, built-in variables local in all buffers:} +@result{} ((mark-active . nil) + (buffer-undo-list nil) + (mode-name . "Fundamental") + @dots{} +@group + ;; @r{Next, non-built-in local variables.} + ;; @r{This one is local and void:} + foobar + ;; @r{This one is local and nonvoid:} + (bind-me . 69)) +@end group +@end example + +Note that storing new values into the @sc{cdr}s of cons cells in this +list does @emph{not} change the local values of the variables. +@end defun + +@deffn Command kill-local-variable variable +This function deletes the buffer-local binding (if any) for +@var{variable} (a symbol) in the current buffer. As a result, the +global (default) binding of @var{variable} becomes visible in this +buffer. Usually this results in a change in the value of +@var{variable}, since the global value is usually different from the +buffer-local value just eliminated. + +If you kill the local binding of a variable that automatically becomes +local when set, this makes the global value visible in the current +buffer. However, if you set the variable again, that will once again +create a local binding for it. + +@code{kill-local-variable} returns @var{variable}. +@end deffn + +@defun kill-all-local-variables +This function eliminates all the buffer-local variable bindings of the +current buffer except for variables marked as ``permanent''. As a +result, the buffer will see the default values of most variables. + +This function also resets certain other information pertaining to the +buffer: it sets the local keymap to @code{nil}, the syntax table to the +value of @code{standard-syntax-table}, and the abbrev table to the value +of @code{fundamental-mode-abbrev-table}. + +Every major mode command begins by calling this function, which has the +effect of switching to Fundamental mode and erasing most of the effects +of the previous major mode. To ensure that this does its job, the +variables that major modes set should not be marked permanent. + +@code{kill-all-local-variables} returns @code{nil}. +@end defun + +@c Emacs 19 feature +@cindex permanent local variable +A local variable is @dfn{permanent} if the variable name (a symbol) has a +@code{permanent-local} property that is non-@code{nil}. Permanent +locals are appropriate for data pertaining to where the file came from +or how to save it, rather than with how to edit the contents. + +@node Default Value +@subsection The Default Value of a Buffer-Local Variable +@cindex default value + + The global value of a variable with buffer-local bindings is also +called the @dfn{default} value, because it is the value that is in +effect except when specifically overridden. + + The functions @code{default-value} and @code{setq-default} access and +change a variable's default value regardless of whether the current +buffer has a buffer-local binding. For example, you could use +@code{setq-default} to change the default setting of +@code{paragraph-start} for most buffers; and this would work even when +you are in a C or Lisp mode buffer which has a buffer-local value for +this variable. + +@c Emacs 19 feature + The special forms @code{defvar} and @code{defconst} also set the +default value (if they set the variable at all), rather than any local +value. + +@defun default-value symbol +This function returns @var{symbol}'s default value. This is the value +that is seen in buffers that do not have their own values for this +variable. If @var{symbol} is not buffer-local, this is equivalent to +@code{symbol-value} (@pxref{Accessing Variables}). +@end defun + +@c Emacs 19 feature +@defun default-boundp variable +The function @code{default-boundp} tells you whether @var{variable}'s +default value is nonvoid. If @code{(default-boundp 'foo)} returns +@code{nil}, then @code{(default-value 'foo)} would get an error. + +@code{default-boundp} is to @code{default-value} as @code{boundp} is to +@code{symbol-value}. +@end defun + +@defspec setq-default symbol value +This sets the default value of @var{symbol} to @var{value}. It does not +evaluate @var{symbol}, but does evaluate @var{value}. The value of the +@code{setq-default} form is @var{value}. + +If a @var{symbol} is not buffer-local for the current buffer, and is not +marked automatically buffer-local, @code{setq-default} has the same +effect as @code{setq}. If @var{symbol} is buffer-local for the current +buffer, then this changes the value that other buffers will see (as long +as they don't have a buffer-local value), but not the value that the +current buffer sees. + +@example +@group +;; @r{In buffer @samp{foo}:} +(make-local-variable 'local) + @result{} local +@end group +@group +(setq local 'value-in-foo) + @result{} value-in-foo +@end group +@group +(setq-default local 'new-default) + @result{} new-default +@end group +@group +local + @result{} value-in-foo +@end group +@group +(default-value 'local) + @result{} new-default +@end group + +@group +;; @r{In (the new) buffer @samp{bar}:} +local + @result{} new-default +@end group +@group +(default-value 'local) + @result{} new-default +@end group +@group +(setq local 'another-default) + @result{} another-default +@end group +@group +(default-value 'local) + @result{} another-default +@end group + +@group +;; @r{Back in buffer @samp{foo}:} +local + @result{} value-in-foo +(default-value 'local) + @result{} another-default +@end group +@end example +@end defspec + +@defun set-default symbol value +This function is like @code{setq-default}, except that @var{symbol} is +evaluated. + +@example +@group +(set-default (car '(a b c)) 23) + @result{} 23 +@end group +@group +(default-value 'a) + @result{} 23 +@end group +@end example +@end defun +