diff options
| author | Chong Yidong | 2012-01-22 00:04:55 +0800 |
|---|---|---|
| committer | Chong Yidong | 2012-01-22 00:04:55 +0800 |
| commit | fead402dddeefba612ab1222b392d5bd0c636400 (patch) | |
| tree | 20af4be88f0e75c3a8310e223d0d971568a95409 | |
| parent | cc6d5805ba054948ee5151e93b4b1318e2a4f5b2 (diff) | |
| download | emacs-fead402dddeefba612ab1222b392d5bd0c636400.tar.gz emacs-fead402dddeefba612ab1222b392d5bd0c636400.zip | |
Emacs Lisp manual updates.
* doc/lispref/intro.texi (A Sample Function Description): Special notation
used for macros too.
* doc/lispref/objects.texi (Ctl-Char Syntax, Other Char Bits): Copyedits.
(Symbol Type): Add xref for keyword symbols.
(Sequence Type): Clarify differences between sequence types.
(Cons Cell Type): Add "linked list" index entry.
(Non-ASCII in Strings): Copyedits.
(Equality Predicates): Symbols with same name need not be eq.
* doc/lispref/numbers.texi (Float Basics): Document isnan, copysign, frexp and
ldexp. Move float-e and float-pi to Math Functions node.
| -rw-r--r-- | doc/lispref/ChangeLog | 15 | ||||
| -rw-r--r-- | doc/lispref/intro.texi | 23 | ||||
| -rw-r--r-- | doc/lispref/numbers.texi | 124 | ||||
| -rw-r--r-- | doc/lispref/objects.texi | 207 | ||||
| -rw-r--r-- | etc/NEWS | 3 |
5 files changed, 202 insertions, 170 deletions
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 872c4f564ac..3c18de96d72 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog | |||
| @@ -1,3 +1,18 @@ | |||
| 1 | 2012-01-21 Chong Yidong <cyd@gnu.org> | ||
| 2 | |||
| 3 | * intro.texi (A Sample Function Description): Special notation | ||
| 4 | used for macros too. | ||
| 5 | |||
| 6 | * objects.texi (Ctl-Char Syntax, Other Char Bits): Copyedits. | ||
| 7 | (Symbol Type): Add xref for keyword symbols. | ||
| 8 | (Sequence Type): Clarify differences between sequence types. | ||
| 9 | (Cons Cell Type): Add "linked list" index entry. | ||
| 10 | (Non-ASCII in Strings): Copyedits. | ||
| 11 | (Equality Predicates): Symbols with same name need not be eq. | ||
| 12 | |||
| 13 | * numbers.texi (Float Basics): Document isnan, copysign, frexp and | ||
| 14 | ldexp. Move float-e and float-pi to Math Functions node. | ||
| 15 | |||
| 1 | 2012-01-21 Glenn Morris <rgm@gnu.org> | 16 | 2012-01-21 Glenn Morris <rgm@gnu.org> |
| 2 | 17 | ||
| 3 | * modes.texi (Auto Major Mode): | 18 | * modes.texi (Auto Major Mode): |
diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi index 64c856d3ed4..a68bcfa0fe7 100644 --- a/doc/lispref/intro.texi +++ b/doc/lispref/intro.texi | |||
| @@ -162,7 +162,7 @@ being described, are formatted like this: @var{first-number}. | |||
| 162 | 162 | ||
| 163 | @cindex @code{nil} | 163 | @cindex @code{nil} |
| 164 | @cindex false | 164 | @cindex false |
| 165 | In Lisp, the symbol @code{nil} has three separate meanings: it | 165 | In Emacs Lisp, the symbol @code{nil} has three separate meanings: it |
| 166 | is a symbol with the name @samp{nil}; it is the logical truth value | 166 | is a symbol with the name @samp{nil}; it is the logical truth value |
| 167 | @var{false}; and it is the empty list---the list of zero elements. | 167 | @var{false}; and it is the empty list---the list of zero elements. |
| 168 | When used as a variable, @code{nil} always has the value @code{nil}. | 168 | When used as a variable, @code{nil} always has the value @code{nil}. |
| @@ -396,13 +396,14 @@ Form', respectively. Commands are simply functions that may be called | |||
| 396 | interactively; macros process their arguments differently from functions | 396 | interactively; macros process their arguments differently from functions |
| 397 | (the arguments are not evaluated), but are presented the same way. | 397 | (the arguments are not evaluated), but are presented the same way. |
| 398 | 398 | ||
| 399 | Special form descriptions use a more complex notation to specify | 399 | The descriptions of macros and special forms use a more complex |
| 400 | optional and repeated arguments because they can break the argument | 400 | notation to specify optional and repeated arguments, because they can |
| 401 | list down into separate arguments in more complicated ways. | 401 | break the argument list down into separate arguments in more |
| 402 | @samp{@r{[}@var{optional-arg}@r{]}} means that @var{optional-arg} is | 402 | complicated ways. @samp{@r{[}@var{optional-arg}@r{]}} means that |
| 403 | optional and @samp{@var{repeated-args}@dots{}} stands for zero or more | 403 | @var{optional-arg} is optional and @samp{@var{repeated-args}@dots{}} |
| 404 | arguments. Parentheses are used when several arguments are grouped into | 404 | stands for zero or more arguments. Parentheses are used when several |
| 405 | additional levels of list structure. Here is an example: | 405 | arguments are grouped into additional levels of list structure. Here |
| 406 | is an example: | ||
| 406 | 407 | ||
| 407 | @defspec count-loop (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} | 408 | @defspec count-loop (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} |
| 408 | This imaginary special form implements a loop that executes the | 409 | This imaginary special form implements a loop that executes the |
| @@ -485,9 +486,9 @@ giving a prefix argument makes @var{here} non-@code{nil}. | |||
| 485 | @end deffn | 486 | @end deffn |
| 486 | 487 | ||
| 487 | @defvar emacs-build-time | 488 | @defvar emacs-build-time |
| 488 | The value of this variable indicates the time at which Emacs was built | 489 | The value of this variable indicates the time at which Emacs was |
| 489 | at the local site. It is a list of three integers, like the value | 490 | built. It is a list of three integers, like the value of |
| 490 | of @code{current-time} (@pxref{Time of Day}). | 491 | @code{current-time} (@pxref{Time of Day}). |
| 491 | 492 | ||
| 492 | @example | 493 | @example |
| 493 | @group | 494 | @group |
diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index 6768ecece9c..77db0f86c26 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi | |||
| @@ -168,34 +168,37 @@ character codepoint. | |||
| 168 | @node Float Basics | 168 | @node Float Basics |
| 169 | @section Floating Point Basics | 169 | @section Floating Point Basics |
| 170 | 170 | ||
| 171 | @cindex @acronym{IEEE} floating point | ||
| 171 | Floating point numbers are useful for representing numbers that are | 172 | Floating point numbers are useful for representing numbers that are |
| 172 | not integral. The precise range of floating point numbers is | 173 | not integral. The precise range of floating point numbers is |
| 173 | machine-specific; it is the same as the range of the C data type | 174 | machine-specific; it is the same as the range of the C data type |
| 174 | @code{double} on the machine you are using. | 175 | @code{double} on the machine you are using. Emacs uses the |
| 176 | @acronym{IEEE} floating point standard where possible (the standard is | ||
| 177 | supported by most modern computers). | ||
| 175 | 178 | ||
| 176 | The read-syntax for floating point numbers requires either a decimal | 179 | The read syntax for floating point numbers requires either a decimal |
| 177 | point (with at least one digit following), an exponent, or both. For | 180 | point (with at least one digit following), an exponent, or both. For |
| 178 | example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and | 181 | example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and |
| 179 | @samp{.15e4} are five ways of writing a floating point number whose | 182 | @samp{.15e4} are five ways of writing a floating point number whose |
| 180 | value is 1500. They are all equivalent. You can also use a minus sign | 183 | value is 1500. They are all equivalent. You can also use a minus |
| 181 | to write negative floating point numbers, as in @samp{-1.0}. | 184 | sign to write negative floating point numbers, as in @samp{-1.0}. |
| 185 | |||
| 186 | Emacs Lisp treats @code{-0.0} as equal to ordinary zero (with | ||
| 187 | respect to @code{equal} and @code{=}), even though the two are | ||
| 188 | distinguishable in the @acronym{IEEE} floating point standard. | ||
| 182 | 189 | ||
| 183 | @cindex @acronym{IEEE} floating point | ||
| 184 | @cindex positive infinity | 190 | @cindex positive infinity |
| 185 | @cindex negative infinity | 191 | @cindex negative infinity |
| 186 | @cindex infinity | 192 | @cindex infinity |
| 187 | @cindex NaN | 193 | @cindex NaN |
| 188 | Most modern computers support the @acronym{IEEE} floating point standard, | 194 | The @acronym{IEEE} floating point standard supports positive |
| 189 | which provides for positive infinity and negative infinity as floating point | 195 | infinity and negative infinity as floating point values. It also |
| 190 | values. It also provides for a class of values called NaN or | 196 | provides for a class of values called NaN or ``not-a-number''; |
| 191 | ``not-a-number''; numerical functions return such values in cases where | 197 | numerical functions return such values in cases where there is no |
| 192 | there is no correct answer. For example, @code{(/ 0.0 0.0)} returns a | 198 | correct answer. For example, @code{(/ 0.0 0.0)} returns a NaN. (NaN |
| 193 | NaN. For practical purposes, there's no significant difference between | 199 | values can also carry a sign, but for practical purposes there's no |
| 194 | different NaN values in Emacs Lisp, and there's no rule for precisely | 200 | significant difference between different NaN values in Emacs Lisp.) |
| 195 | which NaN value should be used in a particular case, so Emacs Lisp | 201 | Here are the read syntaxes for these special floating point values: |
| 196 | doesn't try to distinguish them (but it does report the sign, if you | ||
| 197 | print it). Here are the read syntaxes for these special floating | ||
| 198 | point values: | ||
| 199 | 202 | ||
| 200 | @table @asis | 203 | @table @asis |
| 201 | @item positive infinity | 204 | @item positive infinity |
| @@ -206,16 +209,37 @@ point values: | |||
| 206 | @samp{0.0e+NaN} or @samp{-0.0e+NaN}. | 209 | @samp{0.0e+NaN} or @samp{-0.0e+NaN}. |
| 207 | @end table | 210 | @end table |
| 208 | 211 | ||
| 209 | To test whether a floating point value is a NaN, compare it with | 212 | @defun isnan number |
| 210 | itself using @code{=}. That returns @code{nil} for a NaN, and | 213 | This predicate tests whether its argument is NaN, and returns @code{t} |
| 211 | @code{t} for any other floating point value. | 214 | if so, @code{nil} otherwise. The argument must be a number. |
| 215 | @end defun | ||
| 216 | |||
| 217 | The following functions are specialized for handling floating point | ||
| 218 | numbers: | ||
| 219 | |||
| 220 | @defun frexp x | ||
| 221 | This function returns a cons cell @code{(@var{sig} . @var{exp})}, | ||
| 222 | where @var{sig} and @var{exp} are respectively the significand and | ||
| 223 | exponent of the floating point number @var{x}: | ||
| 224 | |||
| 225 | @smallexample | ||
| 226 | @var{x} = @var{sig} * 2^@var{exp} | ||
| 227 | @end smallexample | ||
| 228 | |||
| 229 | @var{sig} is a floating point number between 0.5 (inclusive) and 1.0 | ||
| 230 | (exclusive). If @var{x} is zero, the return value is @code{(0 . 0)}. | ||
| 231 | @end defun | ||
| 212 | 232 | ||
| 213 | The value @code{-0.0} is distinguishable from ordinary zero in | 233 | @defun ldexp sig &optional exp |
| 214 | @acronym{IEEE} floating point, but Emacs Lisp @code{equal} and | 234 | This function returns a floating point number corresponding to the |
| 215 | @code{=} consider them equal values. | 235 | significand @var{sig} and exponent @var{exp}. |
| 236 | @end defun | ||
| 216 | 237 | ||
| 217 | You can use @code{logb} to extract the binary exponent of a floating | 238 | @defun copysign x1 x2 |
| 218 | point number (or estimate the logarithm of an integer): | 239 | This function copies the sign of @var{x2} to the value of @var{x1}, |
| 240 | and returns the result. @var{x1} and @var{x2} must be floating point | ||
| 241 | numbers. | ||
| 242 | @end defun | ||
| 219 | 243 | ||
| 220 | @defun logb number | 244 | @defun logb number |
| 221 | This function returns the binary exponent of @var{number}. More | 245 | This function returns the binary exponent of @var{number}. More |
| @@ -230,14 +254,6 @@ down to an integer. | |||
| 230 | @end example | 254 | @end example |
| 231 | @end defun | 255 | @end defun |
| 232 | 256 | ||
| 233 | @defvar float-e | ||
| 234 | The mathematical constant @math{e} (2.71828@dots{}). | ||
| 235 | @end defvar | ||
| 236 | |||
| 237 | @defvar float-pi | ||
| 238 | The mathematical constant @math{pi} (3.14159@dots{}). | ||
| 239 | @end defvar | ||
| 240 | |||
| 241 | @node Predicates on Numbers | 257 | @node Predicates on Numbers |
| 242 | @section Type Predicates for Numbers | 258 | @section Type Predicates for Numbers |
| 243 | @cindex predicates for numbers | 259 | @cindex predicates for numbers |
| @@ -1122,35 +1138,15 @@ angle in radians between the vector @code{[@var{x}, @var{y}]} and the | |||
| 1122 | @end defun | 1138 | @end defun |
| 1123 | 1139 | ||
| 1124 | @defun exp arg | 1140 | @defun exp arg |
| 1125 | This is the exponential function; it returns | 1141 | This is the exponential function; it returns @math{e} to the power |
| 1126 | @tex | 1142 | @var{arg}. |
| 1127 | @math{e} | ||
| 1128 | @end tex | ||
| 1129 | @ifnottex | ||
| 1130 | @i{e} | ||
| 1131 | @end ifnottex | ||
| 1132 | to the power @var{arg}. | ||
| 1133 | @tex | ||
| 1134 | @math{e} | ||
| 1135 | @end tex | ||
| 1136 | @ifnottex | ||
| 1137 | @i{e} | ||
| 1138 | @end ifnottex | ||
| 1139 | is a fundamental mathematical constant also called the base of natural | ||
| 1140 | logarithms. | ||
| 1141 | @end defun | 1143 | @end defun |
| 1142 | 1144 | ||
| 1143 | @defun log arg &optional base | 1145 | @defun log arg &optional base |
| 1144 | This function returns the logarithm of @var{arg}, with base @var{base}. | 1146 | This function returns the logarithm of @var{arg}, with base |
| 1145 | If you don't specify @var{base}, the base | 1147 | @var{base}. If you don't specify @var{base}, the natural base |
| 1146 | @tex | 1148 | @math{e} is used. If @var{arg} is negative, it signals a |
| 1147 | @math{e} | 1149 | @code{domain-error} error. |
| 1148 | @end tex | ||
| 1149 | @ifnottex | ||
| 1150 | @i{e} | ||
| 1151 | @end ifnottex | ||
| 1152 | is used. If @var{arg} is negative, it signals a @code{domain-error} | ||
| 1153 | error. | ||
| 1154 | @end defun | 1150 | @end defun |
| 1155 | 1151 | ||
| 1156 | @ignore | 1152 | @ignore |
| @@ -1185,6 +1181,17 @@ This returns the square root of @var{arg}. If @var{arg} is negative, | |||
| 1185 | it signals a @code{domain-error} error. | 1181 | it signals a @code{domain-error} error. |
| 1186 | @end defun | 1182 | @end defun |
| 1187 | 1183 | ||
| 1184 | In addition, Emacs defines the following common mathematical | ||
| 1185 | constants: | ||
| 1186 | |||
| 1187 | @defvar float-e | ||
| 1188 | The mathematical constant @math{e} (2.71828@dots{}). | ||
| 1189 | @end defvar | ||
| 1190 | |||
| 1191 | @defvar float-pi | ||
| 1192 | The mathematical constant @math{pi} (3.14159@dots{}). | ||
| 1193 | @end defvar | ||
| 1194 | |||
| 1188 | @node Random Numbers | 1195 | @node Random Numbers |
| 1189 | @section Random Numbers | 1196 | @section Random Numbers |
| 1190 | @cindex random numbers | 1197 | @cindex random numbers |
| @@ -1218,7 +1225,6 @@ nonnegative and less than @var{limit}. | |||
| 1218 | 1225 | ||
| 1219 | If @var{limit} is @code{t}, it means to choose a new seed based on the | 1226 | If @var{limit} is @code{t}, it means to choose a new seed based on the |
| 1220 | current time of day and on Emacs's process @acronym{ID} number. | 1227 | current time of day and on Emacs's process @acronym{ID} number. |
| 1221 | @c "Emacs'" is incorrect usage! | ||
| 1222 | 1228 | ||
| 1223 | On some machines, any integer representable in Lisp may be the result | 1229 | On some machines, any integer representable in Lisp may be the result |
| 1224 | of @code{random}. On other machines, the result can never be larger | 1230 | of @code{random}. On other machines, the result can never be larger |
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 3fb676edcd4..87bcc20daba 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi | |||
| @@ -427,10 +427,10 @@ codes for these non-@acronym{ASCII} control characters include the | |||
| 427 | @ifnottex | 427 | @ifnottex |
| 428 | 2**26 | 428 | 2**26 |
| 429 | @end ifnottex | 429 | @end ifnottex |
| 430 | bit as well as the code for the corresponding non-control | 430 | bit as well as the code for the corresponding non-control character. |
| 431 | character. Ordinary terminals have no way of generating non-@acronym{ASCII} | 431 | Ordinary text terminals have no way of generating non-@acronym{ASCII} |
| 432 | control characters, but you can generate them straightforwardly using X | 432 | control characters, but you can generate them straightforwardly using |
| 433 | and other window systems. | 433 | X and other window systems. |
| 434 | 434 | ||
| 435 | For historical reasons, Emacs treats the @key{DEL} character as | 435 | For historical reasons, Emacs treats the @key{DEL} character as |
| 436 | the control equivalent of @kbd{?}: | 436 | the control equivalent of @kbd{?}: |
| @@ -501,10 +501,10 @@ character is upper case or lower case. Emacs uses the | |||
| 501 | @end ifnottex | 501 | @end ifnottex |
| 502 | bit to indicate that the shift key was used in typing a control | 502 | bit to indicate that the shift key was used in typing a control |
| 503 | character. This distinction is possible only when you use X terminals | 503 | character. This distinction is possible only when you use X terminals |
| 504 | or other special terminals; ordinary terminals do not report the | 504 | or other special terminals; ordinary text terminals do not report the |
| 505 | distinction to the computer in any way. The Lisp syntax for | 505 | distinction. The Lisp syntax for the shift bit is @samp{\S-}; thus, |
| 506 | the shift bit is @samp{\S-}; thus, @samp{?\C-\S-o} or @samp{?\C-\S-O} | 506 | @samp{?\C-\S-o} or @samp{?\C-\S-O} represents the shifted-control-o |
| 507 | represents the shifted-control-o character. | 507 | character. |
| 508 | 508 | ||
| 509 | @cindex hyper characters | 509 | @cindex hyper characters |
| 510 | @cindex super characters | 510 | @cindex super characters |
| @@ -541,9 +541,9 @@ intended. But you can use one symbol in all of these ways, | |||
| 541 | independently. | 541 | independently. |
| 542 | 542 | ||
| 543 | A symbol whose name starts with a colon (@samp{:}) is called a | 543 | A symbol whose name starts with a colon (@samp{:}) is called a |
| 544 | @dfn{keyword symbol}. These symbols automatically act as constants, and | 544 | @dfn{keyword symbol}. These symbols automatically act as constants, |
| 545 | are normally used only by comparing an unknown symbol with a few | 545 | and are normally used only by comparing an unknown symbol with a few |
| 546 | specific alternatives. | 546 | specific alternatives. @xref{Constant Variables}. |
| 547 | 547 | ||
| 548 | @cindex @samp{\} in symbols | 548 | @cindex @samp{\} in symbols |
| 549 | @cindex backslash in symbols | 549 | @cindex backslash in symbols |
| @@ -617,26 +617,28 @@ all symbols; @pxref{Creating Symbols}.) | |||
| 617 | @subsection Sequence Types | 617 | @subsection Sequence Types |
| 618 | 618 | ||
| 619 | A @dfn{sequence} is a Lisp object that represents an ordered set of | 619 | A @dfn{sequence} is a Lisp object that represents an ordered set of |
| 620 | elements. There are two kinds of sequence in Emacs Lisp, lists and | 620 | elements. There are two kinds of sequence in Emacs Lisp: @dfn{lists} |
| 621 | arrays. Thus, an object of type list or of type array is also | 621 | and @dfn{arrays}. |
| 622 | considered a sequence. | 622 | |
| 623 | 623 | Lists are the most commonly-used sequences. A list can hold | |
| 624 | Arrays are further subdivided into strings, vectors, char-tables and | 624 | elements of any type, and its length can be easily changed by adding |
| 625 | bool-vectors. Vectors can hold elements of any type, but string | 625 | or removing elements. See the next subsection for more about lists. |
| 626 | elements must be characters, and bool-vector elements must be @code{t} | 626 | |
| 627 | or @code{nil}. Char-tables are like vectors except that they are | 627 | Arrays are fixed-length sequences. They are further subdivided into |
| 628 | indexed by any valid character code. The characters in a string can | 628 | strings, vectors, char-tables and bool-vectors. Vectors can hold |
| 629 | have text properties like characters in a buffer (@pxref{Text | 629 | elements of any type, whereas string elements must be characters, and |
| 630 | Properties}), but vectors do not support text properties, even when | 630 | bool-vector elements must be @code{t} or @code{nil}. Char-tables are |
| 631 | their elements happen to be characters. | 631 | like vectors except that they are indexed by any valid character code. |
| 632 | 632 | The characters in a string can have text properties like characters in | |
| 633 | Lists, strings and the other array types are different, but they have | 633 | a buffer (@pxref{Text Properties}), but vectors do not support text |
| 634 | important similarities. For example, all have a length @var{l}, and all | 634 | properties, even when their elements happen to be characters. |
| 635 | have elements which can be indexed from zero to @var{l} minus one. | 635 | |
| 636 | Several functions, called sequence functions, accept any kind of | 636 | Lists, strings and the other array types also share important |
| 637 | sequence. For example, the function @code{elt} can be used to extract | 637 | similarities. For example, all have a length @var{l}, and all have |
| 638 | an element of a sequence, given its index. @xref{Sequences Arrays | 638 | elements which can be indexed from zero to @var{l} minus one. Several |
| 639 | Vectors}. | 639 | functions, called sequence functions, accept any kind of sequence. |
| 640 | For example, the function @code{length} reports the length of any kind | ||
| 641 | of sequence. @xref{Sequences Arrays Vectors}. | ||
| 640 | 642 | ||
| 641 | It is generally impossible to read the same sequence twice, since | 643 | It is generally impossible to read the same sequence twice, since |
| 642 | sequences are always created anew upon reading. If you read the read | 644 | sequences are always created anew upon reading. If you read the read |
| @@ -650,24 +652,27 @@ same object, @code{nil}. | |||
| 650 | @cindex decrement field of register | 652 | @cindex decrement field of register |
| 651 | @cindex pointers | 653 | @cindex pointers |
| 652 | 654 | ||
| 653 | A @dfn{cons cell} is an object that consists of two slots, called the | 655 | A @dfn{cons cell} is an object that consists of two slots, called |
| 654 | @sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} or | 656 | the @sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} any |
| 655 | @dfn{refer to} any Lisp object. We also say that ``the @sc{car} of | 657 | Lisp object. We also say that ``the @sc{car} of this cons cell is'' |
| 656 | this cons cell is'' whatever object its @sc{car} slot currently holds, | 658 | whatever object its @sc{car} slot currently holds, and likewise for |
| 657 | and likewise for the @sc{cdr}. | 659 | the @sc{cdr}. |
| 658 | |||
| 659 | @quotation | ||
| 660 | A note to C programmers: in Lisp, we do not distinguish between | ||
| 661 | ``holding'' a value and ``pointing to'' the value, because pointers in | ||
| 662 | Lisp are implicit. | ||
| 663 | @end quotation | ||
| 664 | 660 | ||
| 661 | @cindex list structure | ||
| 665 | A @dfn{list} is a series of cons cells, linked together so that the | 662 | A @dfn{list} is a series of cons cells, linked together so that the |
| 666 | @sc{cdr} slot of each cons cell holds either the next cons cell or the | 663 | @sc{cdr} slot of each cons cell holds either the next cons cell or the |
| 667 | empty list. The empty list is actually the symbol @code{nil}. | 664 | empty list. The empty list is actually the symbol @code{nil}. |
| 668 | @xref{Lists}, for functions that work on lists. Because most cons | 665 | @xref{Lists}, for details. Because most cons cells are used as part |
| 669 | cells are used as part of lists, the phrase @dfn{list structure} has | 666 | of lists, we refer to any structure made out of cons cells as a |
| 670 | come to refer to any structure made out of cons cells. | 667 | @dfn{list structure}. |
| 668 | |||
| 669 | @cindex linked list | ||
| 670 | @quotation | ||
| 671 | A note to C programmers: a Lisp list thus works as a @dfn{linked list} | ||
| 672 | built up of cons cells. Because pointers in Lisp are implicit, we do | ||
| 673 | not distinguish between a cons cell slot ``holding'' a value versus | ||
| 674 | ``pointing to'' the value. | ||
| 675 | @end quotation | ||
| 671 | 676 | ||
| 672 | @cindex atoms | 677 | @cindex atoms |
| 673 | Because cons cells are so central to Lisp, we also have a word for | 678 | Because cons cells are so central to Lisp, we also have a word for |
| @@ -1025,40 +1030,40 @@ but the newline is ignored if escaped." | |||
| 1025 | @node Non-ASCII in Strings | 1030 | @node Non-ASCII in Strings |
| 1026 | @subsubsection Non-@acronym{ASCII} Characters in Strings | 1031 | @subsubsection Non-@acronym{ASCII} Characters in Strings |
| 1027 | 1032 | ||
| 1028 | You can include a non-@acronym{ASCII} international character in a string | 1033 | You can include a non-@acronym{ASCII} international character in a |
| 1029 | constant by writing it literally. There are two text representations | 1034 | string constant by writing it literally. There are two text |
| 1030 | for non-@acronym{ASCII} characters in Emacs strings (and in buffers): unibyte | 1035 | representations for non-@acronym{ASCII} characters in Emacs strings |
| 1031 | and multibyte. If the string constant is read from a multibyte source, | 1036 | (and in buffers): unibyte and multibyte (@pxref{Text |
| 1032 | such as a multibyte buffer or string, or a file that would be visited as | 1037 | Representations}). If the string constant is read from a multibyte |
| 1033 | multibyte, then the character is read as a multibyte character, and that | 1038 | source, such as a multibyte buffer or string, or a file that would be |
| 1034 | makes the string multibyte. If the string constant is read from a | 1039 | visited as multibyte, then Emacs reads the non-@acronym{ASCII} |
| 1035 | unibyte source, then the character is read as unibyte and that makes the | 1040 | character as a multibyte character and automatically makes the string |
| 1036 | string unibyte. | 1041 | a multibyte string. If the string constant is read from a unibyte |
| 1037 | 1042 | source, then Emacs reads the non-@acronym{ASCII} character as unibyte, | |
| 1038 | You can also represent a multibyte non-@acronym{ASCII} character with its | 1043 | and makes the string unibyte. |
| 1039 | character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many | 1044 | |
| 1040 | digits as necessary. (Multibyte non-@acronym{ASCII} character codes are all | 1045 | Instead of writing a non-@acronym{ASCII} character literally into a |
| 1041 | greater than 256.) Any character which is not a valid hex digit | 1046 | multibyte string, you can write it as its character code using a hex |
| 1042 | terminates this construct. If the next character in the string could be | 1047 | escape, @samp{\x@var{nnnnnnn}}, with as many digits as necessary. |
| 1043 | interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to | 1048 | (Multibyte non-@acronym{ASCII} character codes are all greater than |
| 1044 | terminate the hex escape---for example, @w{@samp{\xe0\ }} represents | 1049 | 256.) You can also specify a character in a multibyte string using |
| 1045 | one character, @samp{a} with grave accent. @w{@samp{\ }} in a string | 1050 | the @samp{\u} or @samp{\U} Unicode escape syntax (@pxref{General |
| 1046 | constant is just like backslash-newline; it does not contribute any | 1051 | Escape Syntax}). In either case, any character which is not a valid |
| 1047 | character to the string, but it does terminate the preceding hex escape. | 1052 | hex digit terminates the construct. If the next character in the |
| 1053 | string could be interpreted as a hex digit, write @w{@samp{\ }} | ||
| 1054 | (backslash and space) to terminate the hex escape---for example, | ||
| 1055 | @w{@samp{\xe0\ }} represents one character, @samp{a} with grave | ||
| 1056 | accent. @w{@samp{\ }} in a string constant is just like | ||
| 1057 | backslash-newline; it does not contribute any character to the string, | ||
| 1058 | but it does terminate the preceding hex escape. Using any hex escape | ||
| 1059 | in a string (even for an @acronym{ASCII} character) automatically | ||
| 1060 | forces the string to be multibyte. | ||
| 1048 | 1061 | ||
| 1049 | You can represent a unibyte non-@acronym{ASCII} character with its | 1062 | You can represent a unibyte non-@acronym{ASCII} character with its |
| 1050 | character code, which must be in the range from 128 (0200 octal) to | 1063 | character code, which must be in the range from 128 (0200 octal) to |
| 1051 | 255 (0377 octal). If you write all such character codes in octal and | 1064 | 255 (0377 octal). If you write all such character codes in octal and |
| 1052 | the string contains no other characters forcing it to be multibyte, | 1065 | the string contains no other characters forcing it to be multibyte, |
| 1053 | this produces a unibyte string. However, using any hex escape in a | 1066 | this produces a unibyte string. |
| 1054 | string (even for an @acronym{ASCII} character) forces the string to be | ||
| 1055 | multibyte. | ||
| 1056 | |||
| 1057 | You can also specify characters in a string by their numeric values | ||
| 1058 | in Unicode, using @samp{\u} and @samp{\U} (@pxref{Character Type}). | ||
| 1059 | |||
| 1060 | @xref{Text Representations}, for more information about the two | ||
| 1061 | text representations. | ||
| 1062 | 1067 | ||
| 1063 | @node Nonprinting Characters | 1068 | @node Nonprinting Characters |
| 1064 | @subsubsection Nonprinting Characters in Strings | 1069 | @subsubsection Nonprinting Characters in Strings |
| @@ -1922,23 +1927,24 @@ This function returns a symbol naming the primitive type of | |||
| 1922 | @section Equality Predicates | 1927 | @section Equality Predicates |
| 1923 | @cindex equality | 1928 | @cindex equality |
| 1924 | 1929 | ||
| 1925 | Here we describe functions that test for equality between any two | 1930 | Here we describe functions that test for equality between two |
| 1926 | objects. Other functions test equality of contents between objects of specific | 1931 | objects. Other functions test equality of contents between objects of |
| 1927 | types, e.g., strings. For these predicates, see the appropriate chapter | 1932 | specific types, e.g.@: strings. For these predicates, see the |
| 1928 | describing the data type. | 1933 | appropriate chapter describing the data type. |
| 1929 | 1934 | ||
| 1930 | @defun eq object1 object2 | 1935 | @defun eq object1 object2 |
| 1931 | This function returns @code{t} if @var{object1} and @var{object2} are | 1936 | This function returns @code{t} if @var{object1} and @var{object2} are |
| 1932 | the same object, @code{nil} otherwise. | 1937 | the same object, and @code{nil} otherwise. |
| 1933 | 1938 | ||
| 1934 | @code{eq} returns @code{t} if @var{object1} and @var{object2} are | 1939 | If @var{object1} and @var{object2} are integers with the same value, |
| 1935 | integers with the same value. Also, since symbol names are normally | 1940 | they are considered to be the same object (i.e.@: @code{eq} returns |
| 1936 | unique, if the arguments are symbols with the same name, they are | 1941 | @code{t}). If @var{object1} and @var{object2} are symbols with the |
| 1937 | @code{eq}. For other types (e.g., lists, vectors, strings), two | 1942 | same name, they are normally the same object---but see @ref{Creating |
| 1938 | arguments with the same contents or elements are not necessarily | 1943 | Symbols} for exceptions. For other types (e.g.@: lists, vectors, |
| 1939 | @code{eq} to each other: they are @code{eq} only if they are the same | 1944 | strings), two arguments with the same contents or elements are not |
| 1940 | object, meaning that a change in the contents of one will be reflected | 1945 | necessarily @code{eq} to each other: they are @code{eq} only if they |
| 1941 | by the same change in the contents of the other. | 1946 | are the same object, meaning that a change in the contents of one will |
| 1947 | be reflected by the same change in the contents of the other. | ||
| 1942 | 1948 | ||
| 1943 | @example | 1949 | @example |
| 1944 | @group | 1950 | @group |
| @@ -1988,6 +1994,7 @@ by the same change in the contents of the other. | |||
| 1988 | @end group | 1994 | @end group |
| 1989 | @end example | 1995 | @end example |
| 1990 | 1996 | ||
| 1997 | @noindent | ||
| 1991 | The @code{make-symbol} function returns an uninterned symbol, distinct | 1998 | The @code{make-symbol} function returns an uninterned symbol, distinct |
| 1992 | from the symbol that is used if you write the name in a Lisp expression. | 1999 | from the symbol that is used if you write the name in a Lisp expression. |
| 1993 | Distinct symbols with the same name are not @code{eq}. @xref{Creating | 2000 | Distinct symbols with the same name are not @code{eq}. @xref{Creating |
| @@ -2003,11 +2010,11 @@ Symbols}. | |||
| 2003 | 2010 | ||
| 2004 | @defun equal object1 object2 | 2011 | @defun equal object1 object2 |
| 2005 | This function returns @code{t} if @var{object1} and @var{object2} have | 2012 | This function returns @code{t} if @var{object1} and @var{object2} have |
| 2006 | equal components, @code{nil} otherwise. Whereas @code{eq} tests if its | 2013 | equal components, and @code{nil} otherwise. Whereas @code{eq} tests |
| 2007 | arguments are the same object, @code{equal} looks inside nonidentical | 2014 | if its arguments are the same object, @code{equal} looks inside |
| 2008 | arguments to see if their elements or contents are the same. So, if two | 2015 | nonidentical arguments to see if their elements or contents are the |
| 2009 | objects are @code{eq}, they are @code{equal}, but the converse is not | 2016 | same. So, if two objects are @code{eq}, they are @code{equal}, but |
| 2010 | always true. | 2017 | the converse is not always true. |
| 2011 | 2018 | ||
| 2012 | @example | 2019 | @example |
| 2013 | @group | 2020 | @group |
| @@ -2059,13 +2066,13 @@ always true. | |||
| 2059 | @end example | 2066 | @end example |
| 2060 | 2067 | ||
| 2061 | Comparison of strings is case-sensitive, but does not take account of | 2068 | Comparison of strings is case-sensitive, but does not take account of |
| 2062 | text properties---it compares only the characters in the strings. Use | 2069 | text properties---it compares only the characters in the strings. |
| 2063 | @code{equal-including-properties} to also compare text properties. For | 2070 | @xref{Text Properties}. Use @code{equal-including-properties} to also |
| 2064 | technical reasons, a unibyte string and a multibyte string are | 2071 | compare text properties. For technical reasons, a unibyte string and |
| 2065 | @code{equal} if and only if they contain the same sequence of | 2072 | a multibyte string are @code{equal} if and only if they contain the |
| 2066 | character codes and all these codes are either in the range 0 through | 2073 | same sequence of character codes and all these codes are either in the |
| 2067 | 127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}). | 2074 | range 0 through 127 (@acronym{ASCII}) or 160 through 255 |
| 2068 | (@pxref{Text Representations}). | 2075 | (@code{eight-bit-graphic}). (@pxref{Text Representations}). |
| 2069 | 2076 | ||
| 2070 | @example | 2077 | @example |
| 2071 | @group | 2078 | @group |
| @@ -1367,6 +1367,9 @@ This means that the empty symbol can now be read back. Also, #: by itself | |||
| 1367 | (when not immediately followed by a possible symbol character) stands for | 1367 | (when not immediately followed by a possible symbol character) stands for |
| 1368 | an empty uninterned symbol. | 1368 | an empty uninterned symbol. |
| 1369 | 1369 | ||
| 1370 | +++ | ||
| 1371 | ** New math functions `isnan', `copysign', `frexp', `ldexp'. | ||
| 1372 | |||
| 1370 | ** Obsolete functions and variables | 1373 | ** Obsolete functions and variables |
| 1371 | 1374 | ||
| 1372 | *** buffer-substring-filters is obsolete. | 1375 | *** buffer-substring-filters is obsolete. |