comparison lispref/objects.texi @ 25751:467b88fab665

*** empty log message ***
author Richard M. Stallman <rms@gnu.org>
date Fri, 17 Sep 1999 06:59:04 +0000
parents 7451b1458af1
children d3cc464b9e87
comparison
equal deleted inserted replaced
25750:f1968a807f56 25751:467b88fab665
23 @cindex primitive type 23 @cindex primitive type
24 A few fundamental object types are built into Emacs. These, from 24 A few fundamental object types are built into Emacs. These, from
25 which all other types are constructed, are called @dfn{primitive 25 which all other types are constructed, are called @dfn{primitive
26 types}. Each object belongs to one and only one primitive type. These 26 types}. Each object belongs to one and only one primitive type. These
27 types include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol}, 27 types include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol},
28 @dfn{string}, @dfn{vector}, @dfn{subr}, @dfn{byte-code function}, plus 28 @dfn{string}, @dfn{vector}, @dfn{subr}, and @dfn{byte-code function}, plus
29 several special types, such as @dfn{buffer}, that are related to 29 several special types, such as @dfn{buffer}, that are related to
30 editing. (@xref{Editing Types}.) 30 editing. (@xref{Editing Types}.)
31 31
32 Each primitive type has a corresponding Lisp function that checks 32 Each primitive type has a corresponding Lisp function that checks
33 whether an object is a member of that type. 33 whether an object is a member of that type.
50 @menu 50 @menu
51 * Printed Representation:: How Lisp objects are represented as text. 51 * Printed Representation:: How Lisp objects are represented as text.
52 * Comments:: Comments and their formatting conventions. 52 * Comments:: Comments and their formatting conventions.
53 * Programming Types:: Types found in all Lisp systems. 53 * Programming Types:: Types found in all Lisp systems.
54 * Editing Types:: Types specific to Emacs. 54 * Editing Types:: Types specific to Emacs.
55 * Circular Objects:: Read syntax for circular structure.
55 * Type Predicates:: Tests related to types. 56 * Type Predicates:: Tests related to types.
56 * Equality Predicates:: Tests of equality between any two objects. 57 * Equality Predicates:: Tests of equality between any two objects.
57 @end menu 58 @end menu
58 59
59 @node Printed Representation 60 @node Printed Representation
144 * Array Type:: Arrays include strings and vectors. 145 * Array Type:: Arrays include strings and vectors.
145 * String Type:: An (efficient) array of characters. 146 * String Type:: An (efficient) array of characters.
146 * Vector Type:: One-dimensional arrays. 147 * Vector Type:: One-dimensional arrays.
147 * Char-Table Type:: One-dimensional sparse arrays indexed by characters. 148 * Char-Table Type:: One-dimensional sparse arrays indexed by characters.
148 * Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}. 149 * Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}.
150 * Hash Table Type:: Super-fast lookup tables.
149 * Function Type:: A piece of executable code you can call from elsewhere. 151 * Function Type:: A piece of executable code you can call from elsewhere.
150 * Macro Type:: A method of expanding an expression into another 152 * Macro Type:: A method of expanding an expression into another
151 expression, more fundamental but less pretty. 153 expression, more fundamental but less pretty.
152 * Primitive Function Type:: A function written in C, callable from Lisp. 154 * Primitive Function Type:: A function written in C, callable from Lisp.
153 * Byte-Code Type:: A function written in Lisp, then compiled. 155 * Byte-Code Type:: A function written in Lisp, then compiled.
162 134217727 (28 bits; i.e., 164 134217727 (28 bits; i.e.,
163 @ifinfo 165 @ifinfo
164 -2**27 166 -2**27
165 @end ifinfo 167 @end ifinfo
166 @tex 168 @tex
167 $-2^{27}$ 169 @math{-2^{27}}
168 @end tex 170 @end tex
169 to 171 to
170 @ifinfo 172 @ifinfo
171 2**27 - 1) 173 2**27 - 1)
172 @end ifinfo 174 @end ifinfo
173 @tex 175 @tex
174 $2^{28}-1$) 176 @math{2^{28}-1})
175 @end tex 177 @end tex
176 on most machines. (Some machines may provide a wider range.) It is 178 on most machines. (Some machines may provide a wider range.) It is
177 important to note that the Emacs Lisp arithmetic functions do not check 179 important to note that the Emacs Lisp arithmetic functions do not check
178 for overflow. Thus @code{(1+ 134217727)} is @minus{}134217728 on most 180 for overflow. Thus @code{(1+ 134217727)} is @minus{}134217728 on most
179 machines. 181 machines.
185 187
186 @example 188 @example
187 @group 189 @group
188 -1 ; @r{The integer -1.} 190 -1 ; @r{The integer -1.}
189 1 ; @r{The integer 1.} 191 1 ; @r{The integer 1.}
190 1. ; @r{Also The integer 1.} 192 1. ; @r{Also the integer 1.}
191 +1 ; @r{Also the integer 1.} 193 +1 ; @r{Also the integer 1.}
192 268435457 ; @r{Also the integer 1 on a 28-bit implementation.} 194 268435457 ; @r{Also the integer 1 on a 28-bit implementation.}
193 @end group 195 @end group
194 @end example 196 @end example
195 197
210 212
211 @xref{Numbers}, for more information. 213 @xref{Numbers}, for more information.
212 214
213 @node Character Type 215 @node Character Type
214 @subsection Character Type 216 @subsection Character Type
215 @cindex @sc{ASCII} character codes 217 @cindex @sc{ascii} character codes
216 218
217 A @dfn{character} in Emacs Lisp is nothing more than an integer. In 219 A @dfn{character} in Emacs Lisp is nothing more than an integer. In
218 other words, characters are represented by their character codes. For 220 other words, characters are represented by their character codes. For
219 example, the character @kbd{A} is represented as the @w{integer 65}. 221 example, the character @kbd{A} is represented as the @w{integer 65}.
220 222
288 ?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}} 290 ?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}}
289 ?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}} 291 ?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}}
290 ?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}} 292 ?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}}
291 ?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}} 293 ?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}}
292 ?\\ @result{} 92 ; @r{backslash character, @kbd{\}} 294 ?\\ @result{} 92 ; @r{backslash character, @kbd{\}}
295 ?\d @result{} 127 ; @r{delete character, @key{DEL}}
293 @end example 296 @end example
294 297
295 @cindex escape sequence 298 @cindex escape sequence
296 These sequences which start with backslash are also known as 299 These sequences which start with backslash are also known as
297 @dfn{escape sequences}, because backslash plays the role of an escape 300 @dfn{escape sequences}, because backslash plays the role of an escape
310 @example 313 @example
311 ?\^I @result{} 9 ?\C-I @result{} 9 314 ?\^I @result{} 9 ?\C-I @result{} 9
312 @end example 315 @end example
313 316
314 In strings and buffers, the only control characters allowed are those 317 In strings and buffers, the only control characters allowed are those
315 that exist in @sc{ASCII}; but for keyboard input purposes, you can turn 318 that exist in @sc{ascii}; but for keyboard input purposes, you can turn
316 any character into a control character with @samp{C-}. The character 319 any character into a control character with @samp{C-}. The character
317 codes for these non-@sc{ASCII} control characters include the 320 codes for these non-@sc{ascii} control characters include the
318 @tex 321 @tex
319 $2^{26}$ 322 @math{2^{26}}
320 @end tex 323 @end tex
321 @ifinfo 324 @ifinfo
322 2**26 325 2**26
323 @end ifinfo 326 @end ifinfo
324 bit as well as the code for the corresponding non-control 327 bit as well as the code for the corresponding non-control
325 character. Ordinary terminals have no way of generating non-@sc{ASCII} 328 character. Ordinary terminals have no way of generating non-@sc{ascii}
326 control characters, but you can generate them straightforwardly using X 329 control characters, but you can generate them straightforwardly using X
327 and other window systems. 330 and other window systems.
328 331
329 For historical reasons, Emacs treats the @key{DEL} character as 332 For historical reasons, Emacs treats the @key{DEL} character as
330 the control equivalent of @kbd{?}: 333 the control equivalent of @kbd{?}:
347 350
348 @cindex meta characters 351 @cindex meta characters
349 A @dfn{meta character} is a character typed with the @key{META} 352 A @dfn{meta character} is a character typed with the @key{META}
350 modifier key. The integer that represents such a character has the 353 modifier key. The integer that represents such a character has the
351 @tex 354 @tex
352 $2^{27}$ 355 @math{2^{27}}
353 @end tex 356 @end tex
354 @ifinfo 357 @ifinfo
355 2**27 358 2**27
356 @end ifinfo 359 @end ifinfo
357 bit set (which on most machines makes it a negative number). We 360 bit set (which on most machines makes it a negative number). We
358 use high bits for this and other modifiers to make possible a wide range 361 use high bits for this and other modifiers to make possible a wide range
359 of basic character codes. 362 of basic character codes.
360 363
361 In a string, the 364 In a string, the
362 @tex 365 @tex
363 $2^{7}$ 366 @math{2^{7}}
364 @end tex 367 @end tex
365 @ifinfo 368 @ifinfo
366 2**7 369 2**7
367 @end ifinfo 370 @end ifinfo
368 bit attached to an ASCII character indicates a meta character; thus, the 371 bit attached to an ASCII character indicates a meta character; thus, the
369 meta characters that can fit in a string have codes in the range from 372 meta characters that can fit in a string have codes in the range from
370 128 to 255, and are the meta versions of the ordinary @sc{ASCII} 373 128 to 255, and are the meta versions of the ordinary @sc{ascii}
371 characters. (In Emacs versions 18 and older, this convention was used 374 characters. (In Emacs versions 18 and older, this convention was used
372 for characters outside of strings as well.) 375 for characters outside of strings as well.)
373 376
374 The read syntax for meta characters uses @samp{\M-}. For example, 377 The read syntax for meta characters uses @samp{\M-}. For example,
375 @samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with 378 @samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with
377 syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A}, 380 syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A},
378 or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as 381 or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as
379 @samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}. 382 @samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
380 383
381 The case of a graphic character is indicated by its character code; 384 The case of a graphic character is indicated by its character code;
382 for example, @sc{ASCII} distinguishes between the characters @samp{a} 385 for example, @sc{ascii} distinguishes between the characters @samp{a}
383 and @samp{A}. But @sc{ASCII} has no way to represent whether a control 386 and @samp{A}. But @sc{ascii} has no way to represent whether a control
384 character is upper case or lower case. Emacs uses the 387 character is upper case or lower case. Emacs uses the
385 @tex 388 @tex
386 $2^{25}$ 389 @math{2^{25}}
387 @end tex 390 @end tex
388 @ifinfo 391 @ifinfo
389 2**25 392 2**25
390 @end ifinfo 393 @end ifinfo
391 bit to indicate that the shift key was used in typing a control 394 bit to indicate that the shift key was used in typing a control
403 for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. (Case is 406 for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. (Case is
404 significant in these prefixes.) Thus, @samp{?\H-\M-\A-x} represents 407 significant in these prefixes.) Thus, @samp{?\H-\M-\A-x} represents
405 @kbd{Alt-Hyper-Meta-x}. 408 @kbd{Alt-Hyper-Meta-x}.
406 @tex 409 @tex
407 Numerically, the 410 Numerically, the
408 bit values are $2^{22}$ for alt, $2^{23}$ for super and $2^{24}$ for hyper. 411 bit values are @math{2^{22}} for alt, @math{2^{23}} for super and @math{2^{24}} for hyper.
409 @end tex 412 @end tex
410 @ifinfo 413 @ifinfo
411 Numerically, the 414 Numerically, the
412 bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper. 415 bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
413 @end ifinfo 416 @end ifinfo
418 Finally, the most general read syntax for a character represents the 421 Finally, the most general read syntax for a character represents the
419 character code in either octal or hex. To use octal, write a question 422 character code in either octal or hex. To use octal, write a question
420 mark followed by a backslash and the octal character code (up to three 423 mark followed by a backslash and the octal character code (up to three
421 octal digits); thus, @samp{?\101} for the character @kbd{A}, 424 octal digits); thus, @samp{?\101} for the character @kbd{A},
422 @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the 425 @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
423 character @kbd{C-b}. Although this syntax can represent any @sc{ASCII} 426 character @kbd{C-b}. Although this syntax can represent any @sc{ascii}
424 character, it is preferred only when the precise octal value is more 427 character, it is preferred only when the precise octal value is more
425 important than the @sc{ASCII} representation. 428 important than the @sc{ascii} representation.
426 429
427 @example 430 @example
428 @group 431 @group
429 ?\012 @result{} 10 ?\n @result{} 10 ?\C-j @result{} 10 432 ?\012 @result{} 10 ?\n @result{} 10 ?\C-j @result{} 10
430 ?\101 @result{} 65 ?A @result{} 65 433 ?\101 @result{} 65 ?A @result{} 65
518 +-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.} 521 +-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
519 ; @r{These characters need not be escaped.} 522 ; @r{These characters need not be escaped.}
520 @end group 523 @end group
521 @end example 524 @end example
522 525
526 @cindex @samp{#:} read syntax
527 Normally the Lisp reader interns all symbols (@pxref{Creating
528 Symbols}). To prevent interning, you can write @samp{#:} before the
529 name of the symbol.
530
523 @node Sequence Type 531 @node Sequence Type
524 @subsection Sequence Types 532 @subsection Sequence Types
525 533
526 A @dfn{sequence} is a Lisp object that represents an ordered set of 534 A @dfn{sequence} is a Lisp object that represents an ordered set of
527 elements. There are two kinds of sequence in Emacs Lisp, lists and 535 elements. There are two kinds of sequence in Emacs Lisp, lists and
557 @cindex decrement field of register 565 @cindex decrement field of register
558 @cindex pointers 566 @cindex pointers
559 567
560 A @dfn{cons cell} is an object that consists of two slots, called the 568 A @dfn{cons cell} is an object that consists of two slots, called the
561 @sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} or 569 @sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} or
562 @dfn{refer to} any Lisp object. We also say that the ``the @sc{car} of 570 @dfn{refer to} any Lisp object. We also say that ``the @sc{car} of
563 this cons cell is'' whatever object its @sc{car} slot currently holds, 571 this cons cell is'' whatever object its @sc{car} slot currently holds,
564 and likewise for the @sc{cdr}. 572 and likewise for the @sc{cdr}.
565 573
566 @quotation 574 @quotation
567 A note to C programmers: in Lisp, we do not distinguish between 575 A note to C programmers: in Lisp, we do not distinguish between
792 @noindent 800 @noindent
793 sets the variable @code{alist-of-colors} to an alist of three elements. In the 801 sets the variable @code{alist-of-colors} to an alist of three elements. In the
794 first element, @code{rose} is the key and @code{red} is the value. 802 first element, @code{rose} is the key and @code{red} is the value.
795 803
796 @xref{Association Lists}, for a further explanation of alists and for 804 @xref{Association Lists}, for a further explanation of alists and for
797 functions that work on alists. 805 functions that work on alists. @xref{Hash Tables}, for another kind of
806 lookup table, which is much faster for handling a large number of keys.
798 807
799 @node Array Type 808 @node Array Type
800 @subsection Array Type 809 @subsection Array Type
801 810
802 An @dfn{array} is composed of an arbitrary number of slots for 811 An @dfn{array} is composed of an arbitrary number of slots for
882 @end example 891 @end example
883 892
884 @node Non-ASCII in Strings 893 @node Non-ASCII in Strings
885 @subsubsection Non-ASCII Characters in Strings 894 @subsubsection Non-ASCII Characters in Strings
886 895
887 You can include a non-@sc{ASCII} international character in a string 896 You can include a non-@sc{ascii} international character in a string
888 constant by writing it literally. There are two text representations 897 constant by writing it literally. There are two text representations
889 for non-@sc{ASCII} characters in Emacs strings (and in buffers): unibyte 898 for non-@sc{ascii} characters in Emacs strings (and in buffers): unibyte
890 and multibyte. If the string constant is read from a multibyte source, 899 and multibyte. If the string constant is read from a multibyte source,
891 such as a multibyte buffer or string, or a file that would be visited as 900 such as a multibyte buffer or string, or a file that would be visited as
892 multibyte, then the character is read as a multibyte character, and that 901 multibyte, then the character is read as a multibyte character, and that
893 makes the string multibyte. If the string constant is read from a 902 makes the string multibyte. If the string constant is read from a
894 unibyte source, then the character is read as unibyte and that makes the 903 unibyte source, then the character is read as unibyte and that makes the
895 string unibyte. 904 string unibyte.
896 905
897 You can also represent a multibyte non-@sc{ASCII} character with its 906 You can also represent a multibyte non-@sc{ASCII} character with its
898 character code, using a hex escape, @samp{\x@var{nnnnnnn}}, with as many 907 character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many
899 digits as necessary. (Multibyte non-@sc{ASCII} character codes are all 908 digits as necessary. (Multibyte non-@sc{ASCII} character codes are all
900 greater than 256.) Any character which is not a valid hex digit 909 greater than 256.) Any character which is not a valid hex digit
901 terminates this construct. If the next character in the string could be 910 terminates this construct. If the next character in the string could be
902 interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to 911 interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to
903 terminate the hex escape---for example, @w{@samp{\x8e0\ }} represents 912 terminate the hex escape---for example, @w{@samp{\x8e0\ }} represents
904 one character, @samp{a} with grave accent. @w{@samp{\ }} in a string 913 one character, @samp{a} with grave accent. @w{@samp{\ }} in a string
905 constant is just like backslash-newline; it does not contribute any 914 constant is just like backslash-newline; it does not contribute any
906 character to the string, but it does terminate the preceding hex escape. 915 character to the string, but it does terminate the preceding hex escape.
907 916
908 Using a multibyte hex escape forces the string to multibyte. You can 917 Using a multibyte hex escape forces the string to multibyte. You can
909 represent a unibyte non-@sc{ASCII} character with its character code, 918 represent a unibyte non-@sc{ascii} character with its character code,
910 which must be in the range from 128 (0200 octal) to 255 (0377 octal). 919 which must be in the range from 128 (0200 octal) to 255 (0377 octal).
911 This forces a unibyte string. 920 This forces a unibyte string.
912 921
913 @xref{Text Representations}, for more information about the two 922 @xref{Text Representations}, for more information about the two
914 text representations. 923 text representations.
923 them, like this: @code{"\t, \C-a"}. @xref{Character Type}, for a 932 them, like this: @code{"\t, \C-a"}. @xref{Character Type}, for a
924 description of the read syntax for characters. 933 description of the read syntax for characters.
925 934
926 However, not all of the characters you can write with backslash 935 However, not all of the characters you can write with backslash
927 escape-sequences are valid in strings. The only control characters that 936 escape-sequences are valid in strings. The only control characters that
928 a string can hold are the @sc{ASCII} control characters. Strings do not 937 a string can hold are the @sc{ascii} control characters. Strings do not
929 distinguish case in @sc{ASCII} control characters. 938 distinguish case in @sc{ascii} control characters.
930 939
931 Properly speaking, strings cannot hold meta characters; but when a 940 Properly speaking, strings cannot hold meta characters; but when a
932 string is to be used as a key sequence, there is a special convention 941 string is to be used as a key sequence, there is a special convention
933 that provides a way to represent meta versions of @sc{ASCII} characters in a 942 that provides a way to represent meta versions of @sc{ascii} characters in a
934 string. If you use the @samp{\M-} syntax to indicate a meta character 943 string. If you use the @samp{\M-} syntax to indicate a meta character
935 in a string constant, this sets the 944 in a string constant, this sets the
936 @tex 945 @tex
937 $2^{7}$ 946 @math{2^{7}}
938 @end tex 947 @end tex
939 @ifinfo 948 @ifinfo
940 2**7 949 2**7
941 @end ifinfo 950 @end ifinfo
942 bit of the character in the string. If the string is used in 951 bit of the character in the string. If the string is used in
1041 @subsection Bool-Vector Type 1050 @subsection Bool-Vector Type
1042 1051
1043 A @dfn{bool-vector} is a one-dimensional array of elements that 1052 A @dfn{bool-vector} is a one-dimensional array of elements that
1044 must be @code{t} or @code{nil}. 1053 must be @code{t} or @code{nil}.
1045 1054
1046 The printed representation of a Bool-vector is like a string, except 1055 The printed representation of a bool-vector is like a string, except
1047 that it begins with @samp{#&} followed by the length. The string 1056 that it begins with @samp{#&} followed by the length. The string
1048 constant that follows actually specifies the contents of the bool-vector 1057 constant that follows actually specifies the contents of the bool-vector
1049 as a bitmap---each ``character'' in the string contains 8 bits, which 1058 as a bitmap---each ``character'' in the string contains 8 bits, which
1050 specify the next 8 elements of the bool-vector (1 stands for @code{t}, 1059 specify the next 8 elements of the bool-vector (1 stands for @code{t},
1051 and 0 for @code{nil}). The least significant bits of the character 1060 and 0 for @code{nil}). The least significant bits of the character
1061 ;; @r{These are equal since only the first 3 bits are used.} 1070 ;; @r{These are equal since only the first 3 bits are used.}
1062 (equal #&3"\377" #&3"\007") 1071 (equal #&3"\377" #&3"\007")
1063 @result{} t 1072 @result{} t
1064 @end example 1073 @end example
1065 1074
1075 @node Hash Table Type
1076 @subsection Hash Table Type
1077
1078 A hash table is a very fast kind of lookup table, somewhat like an
1079 alist in that it maps keys to corresponding values, but much faster.
1080 Hash tables are a new feature in Emacs 21; they have no read syntax, and
1081 print using hash notation. @xref{Hash Tables}.
1082
1083 @example
1084 (make-hash-table)
1085 @result{} #<hash-table 'eql nil 0/65 0x83af980>
1086 @end example
1087
1066 @node Function Type 1088 @node Function Type
1067 @subsection Function Type 1089 @subsection Function Type
1068 1090
1069 Just as functions in other programming languages are executable, 1091 Just as functions in other programming languages are executable,
1070 @dfn{Lisp function} objects are pieces of executable code. However, 1092 @dfn{Lisp function} objects are pieces of executable code. However,
1154 1176
1155 @node Autoload Type 1177 @node Autoload Type
1156 @subsection Autoload Type 1178 @subsection Autoload Type
1157 1179
1158 An @dfn{autoload object} is a list whose first element is the symbol 1180 An @dfn{autoload object} is a list whose first element is the symbol
1159 @code{autoload}. It is stored as the function definition of a symbol as 1181 @code{autoload}. It is stored as the function definition of a symbol,
1160 a placeholder for the real definition; it says that the real definition 1182 where it serves as a placeholder for the real definition. The autoload
1161 is found in a file of Lisp code that should be loaded when necessary. 1183 object says that the real definition is found in a file of Lisp code
1162 The autoload object contains the name of the file, plus some other 1184 that should be loaded when necessary. It contains the name of the file,
1163 information about the real definition. 1185 plus some other information about the real definition.
1164 1186
1165 After the file has been loaded, the symbol should have a new function 1187 After the file has been loaded, the symbol should have a new function
1166 definition that is not an autoload object. The new definition is then 1188 definition that is not an autoload object. The new definition is then
1167 called as if it had been there to begin with. From the user's point of 1189 called as if it had been there to begin with. From the user's point of
1168 view, the function call works as expected, using the function definition 1190 view, the function call works as expected, using the function definition
1205 buffer need not be displayed in any window. 1227 buffer need not be displayed in any window.
1206 1228
1207 The contents of a buffer are much like a string, but buffers are not 1229 The contents of a buffer are much like a string, but buffers are not
1208 used like strings in Emacs Lisp, and the available operations are 1230 used like strings in Emacs Lisp, and the available operations are
1209 different. For example, you can insert text efficiently into an 1231 different. For example, you can insert text efficiently into an
1210 existing buffer, whereas ``inserting'' text into a string requires 1232 existing buffer, altering the buffer's contents, whereas ``inserting''
1211 concatenating substrings, and the result is an entirely new string 1233 text into a string requires concatenating substrings, and the result is
1212 object. 1234 an entirely new string object.
1213 1235
1214 Each buffer has a designated position called @dfn{point} 1236 Each buffer has a designated position called @dfn{point}
1215 (@pxref{Positions}). At any time, one buffer is the @dfn{current 1237 (@pxref{Positions}). At any time, one buffer is the @dfn{current
1216 buffer}. Most editing commands act on the contents of the current 1238 buffer}. Most editing commands act on the contents of the current
1217 buffer in the neighborhood of point. Many of the standard Emacs 1239 buffer in the neighborhood of point. Many of the standard Emacs
1428 buffer temporarily in a different display style. Overlays have no read 1450 buffer temporarily in a different display style. Overlays have no read
1429 syntax, and print in hash notation, giving the buffer name and range of 1451 syntax, and print in hash notation, giving the buffer name and range of
1430 positions. 1452 positions.
1431 1453
1432 @xref{Overlays}, for how to create and use overlays. 1454 @xref{Overlays}, for how to create and use overlays.
1455
1456 @node Circular Objects
1457 @section Read Syntax for Circular Objects
1458 @cindex circular structure, read syntax
1459 @cindex shared structure, read syntax
1460 @cindex @samp{#@var{n}=} read syntax
1461 @cindex @samp{#@var{n}#} read syntax
1462
1463 In Emacs 21, to represent shared or circular structure within a
1464 complex of Lisp objects, you can use the reader constructs
1465 @samp{#@var{n}=} and @samp{#@var{n}#}.
1466
1467 Use @code{#@var{n}=} before an object to label it for later reference;
1468 subsequently, you can use @code{#@var{n}#} to refer the same object in
1469 another place. Here, @var{n} is some integer. For example, here is how
1470 to make a list in which the first element recurs as the third element:
1471
1472 @example
1473 (#1=(a) b #1#)
1474 @end example
1475
1476 @noindent
1477 This differs from ordinary syntax such as this
1478
1479 @example
1480 ((a) b (a))
1481 @end example
1482
1483 @noindent
1484 which would result in a list whose first and third elements
1485 look alike but are not the same Lisp object. This shows the difference:
1486
1487 @example
1488 (prog1 nil
1489 (setq x '(#1=(a) b #1#)))
1490 (eq (nth 0 x) (nth 2 x))
1491 @result{} t
1492 (setq x '((a) b (a)))
1493 (eq (nth 0 x) (nth 2 x))
1494 @result{} nil
1495 @end example
1496
1497 You can also use the same syntax to make a circular structure, which
1498 appears as an ``element'' within itself. Here is an example:
1499
1500 @example
1501 #1=(a #1#)
1502 @end example
1503
1504 @noindent
1505 This makes a list whose second element is the list itself.
1506 Here's how you can see that it really works:
1507
1508 @example
1509 (prog1 nil
1510 (setq x '#1=(a #1#)))
1511 (eq x (cadr x))
1512 @result{} t
1513 @end example
1514
1515 The Lisp printer can produce this syntax to record circular and shared
1516 structure in a Lisp object, if you bind the variable @code{print-circle}
1517 to a non-@code{nil} value. @xref{Output Variables}.
1433 1518
1434 @node Type Predicates 1519 @node Type Predicates
1435 @section Type Predicates 1520 @section Type Predicates
1436 @cindex predicates 1521 @cindex predicates
1437 @cindex type checking 1522 @cindex type checking
1762 @end example 1847 @end example
1763 1848
1764 Comparison of strings is case-sensitive, but does not take account of 1849 Comparison of strings is case-sensitive, but does not take account of
1765 text properties---it compares only the characters in the strings. 1850 text properties---it compares only the characters in the strings.
1766 A unibyte string never equals a multibyte string unless the 1851 A unibyte string never equals a multibyte string unless the
1767 contents are entirely @sc{ASCII} (@pxref{Text Representations}). 1852 contents are entirely @sc{ascii} (@pxref{Text Representations}).
1768 1853
1769 @example 1854 @example
1770 @group 1855 @group
1771 (equal "asdf" "ASDF") 1856 (equal "asdf" "ASDF")
1772 @result{} nil 1857 @result{} nil