1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: String Basics, Next: Predicates for Strings, Up: Strings and Characters
55 String and Character Basics
56 ===========================
58 Strings in XEmacs Lisp are arrays that contain an ordered sequence of
59 characters. Characters are their own primitive object type in XEmacs
60 20. However, in XEmacs 19, characters are represented in XEmacs Lisp as
61 integers; whether an integer was intended as a character or not is
62 determined only by how it is used. *Note Character Type::.
64 The length of a string (like any array) is fixed and independent of
65 the string contents, and cannot be altered. Strings in Lisp are _not_
66 terminated by a distinguished character code. (By contrast, strings in
67 C are terminated by a character with ASCII code 0.) This means that
68 any character, including the null character (ASCII code 0), is a valid
71 Since strings are considered arrays, you can operate on them with the
72 general array functions. (*Note Sequences Arrays Vectors::.) For
73 example, you can access or change individual characters in a string
74 using the functions `aref' and `aset' (*note Array Functions::).
76 Strings use an efficient representation for storing the characters
77 in them, and thus take up much less memory than a vector of the same
80 Sometimes you will see strings used to hold key sequences. This
81 exists for backward compatibility with Emacs 18, but should _not_ be
82 used in new code, since many key chords can't be represented at all and
83 others (in particular meta key chords) are confused with accented
86 Strings are useful for holding regular expressions. You can also
87 match regular expressions against strings (*note Regexp Search::). The
88 functions `match-string' (*note Simple Match Data::) and
89 `replace-match' (*note Replacing Match::) are useful for decomposing
90 and modifying strings based on regular expression matching.
92 Like a buffer, a string can contain extents in it. These extents are
93 created when a function such as `buffer-substring' is called on a
94 region with duplicable extents in it. When the string is inserted into
95 a buffer, the extents are inserted along with it. *Note Duplicable
98 *Note Text::, for information about functions that display strings or
99 copy them into buffers. *Note Character Type::, and *Note String
100 Type::, for information about the syntax of characters and strings.
103 File: lispref.info, Node: Predicates for Strings, Next: Creating Strings, Prev: String Basics, Up: Strings and Characters
105 The Predicates for Strings
106 ==========================
108 For more information about general sequence and array predicates,
109 see *Note Sequences Arrays Vectors::, and *Note Arrays::.
111 - Function: stringp object
112 This function returns `t' if OBJECT is a string, `nil' otherwise.
114 - Function: char-or-string-p object
115 This function returns `t' if OBJECT is a string or a character,
118 In XEmacs addition, this function also returns `t' if OBJECT is an
119 integer that can be represented as a character. This is because
120 of compatibility with previous XEmacs and should not be depended
124 File: lispref.info, Node: Creating Strings, Next: Predicates for Characters, Prev: Predicates for Strings, Up: Strings and Characters
129 The following functions create strings, either from scratch, or by
130 putting strings together, or by taking them apart.
132 - Function: string &rest characters
133 This function returns a new string made up of CHARACTERS.
135 (string ?X ?E ?m ?a ?c ?s)
140 Analogous functions operating on other data types include `list',
141 `cons' (*note Building Lists::), `vector' (*note Vectors::) and
142 `bit-vector' (*note Bit Vectors::). This function has not been
143 available in XEmacs prior to 21.0 and FSF Emacs prior to 20.3.
145 - Function: make-string length character
146 This function returns a new string consisting entirely of LENGTH
147 successive copies of CHARACTER. LENGTH must be a non-negative
155 Other functions to compare with this one include `char-to-string'
156 (*note String Conversion::), `make-vector' (*note Vectors::), and
157 `make-list' (*note Building Lists::).
159 - Function: substring string start &optional end
160 This function returns a new string which consists of those
161 characters from STRING in the range from (and including) the
162 character at the index START up to (but excluding) the character
163 at the index END. The first character is at index zero.
165 (substring "abcdefg" 0 3)
168 Here the index for `a' is 0, the index for `b' is 1, and the index
169 for `c' is 2. Thus, three letters, `abc', are copied from the
170 string `"abcdefg"'. The index 3 marks the character position up
171 to which the substring is copied. The character whose index is 3
172 is actually the fourth character in the string.
174 A negative number counts from the end of the string, so that -1
175 signifies the index of the last character of the string. For
178 (substring "abcdefg" -3 -1)
181 In this example, the index for `e' is -3, the index for `f' is -2,
182 and the index for `g' is -1. Therefore, `e' and `f' are included,
185 When `nil' is used as an index, it stands for the length of the
188 (substring "abcdefg" -3 nil)
191 Omitting the argument END is equivalent to specifying `nil'. It
192 follows that `(substring STRING 0)' returns a copy of all of
195 (substring "abcdefg" 0)
198 But we recommend `copy-sequence' for this purpose (*note Sequence
201 If the characters copied from STRING have duplicable extents or
202 text properties, those are copied into the new string also. *Note
203 Duplicable Extents::.
205 A `wrong-type-argument' error is signaled if either START or END
206 is not an integer or `nil'. An `args-out-of-range' error is
207 signaled if START indicates a character following END, or if
208 either integer is out of range for STRING.
210 Contrast this function with `buffer-substring' (*note Buffer
211 Contents::), which returns a string containing a portion of the
212 text in the current buffer. The beginning of a string is at index
213 0, but the beginning of a buffer is at index 1.
215 - Function: concat &rest sequences
216 This function returns a new string consisting of the characters in
217 the arguments passed to it (along with their text properties, if
218 any). The arguments may be strings, lists of numbers, or vectors
219 of numbers; they are not themselves changed. If `concat' receives
220 no arguments, it returns an empty string.
222 (concat "abc" "-def")
224 (concat "abc" (list 120 (+ 256 121)) [122])
226 ;; `nil' is an empty sequence.
227 (concat "abc" nil "-def")
229 (concat "The " "quick brown " "fox.")
230 => "The quick brown fox."
234 The second example above shows how characters stored in strings are
235 taken modulo 256. In other words, each character in the string is
238 The `concat' function always constructs a new string that is not
239 `eq' to any existing string.
241 When an argument is an integer (not a sequence of integers), it is
242 converted to a string of digits making up the decimal printed
243 representation of the integer. *Don't use this feature; we plan
244 to eliminate it. If you already use this feature, change your
245 programs now!* The proper way to convert an integer to a decimal
246 number in this way is with `format' (*note Formatting Strings::) or
247 `number-to-string' (*note String Conversion::).
254 For information about other concatenation functions, see the
255 description of `mapconcat' in *Note Mapping Functions::, `vconcat'
256 in *Note Vectors::, `bvconcat' in *Note Bit Vectors::, and `append'
257 in *Note Building Lists::.
260 File: lispref.info, Node: Predicates for Characters, Next: Character Codes, Prev: Creating Strings, Up: Strings and Characters
262 The Predicates for Characters
263 =============================
265 - Function: characterp object
266 This function returns `t' if OBJECT is a character.
268 Some functions that work on integers (e.g. the comparison functions
269 <, <=, =, /=, etc. and the arithmetic functions +, -, *, etc.)
270 accept characters and implicitly convert them into integers. In
271 general, functions that work on characters also accept char-ints
272 and implicitly convert them into characters. WARNING: Neither of
273 these behaviors is very desirable, and they are maintained for
274 backward compatibility with old E-Lisp programs that confounded
275 characters and integers willy-nilly. These behaviors may change
276 in the future; therefore, do not rely on them. Instead, convert
277 the characters explicitly using `char-int'.
279 - Function: integer-or-char-p object
280 This function returns `t' if OBJECT is an integer or character.
283 File: lispref.info, Node: Character Codes, Next: Text Comparison, Prev: Predicates for Characters, Up: Strings and Characters
288 - Function: char-int character
289 This function converts a character into an equivalent integer.
290 The resulting integer will always be non-negative. The integers in
291 the range 0 - 255 map to characters as follows:
303 Right half of ISO-8859-1
305 If support for MULE does not exist, these are the only valid
306 character values. When MULE support exists, the values assigned to
307 other characters may vary depending on the particular version of
308 XEmacs, the order in which character sets were loaded, etc., and
309 you should not depend on them.
311 - Function: int-char integer
312 This function converts an integer into the equivalent character.
313 Not all integers correspond to valid characters; use `char-int-p'
314 to determine whether this is the case. If the integer cannot be
315 converted, `nil' is returned.
317 - Function: char-int-p object
318 This function returns `t' if OBJECT is an integer that can be
319 converted into a character.
321 - Function: char-or-char-int-p object
322 This function returns `t' if OBJECT is a character or an integer
323 that can be converted into one.
326 File: lispref.info, Node: Text Comparison, Next: String Conversion, Prev: Character Codes, Up: Strings and Characters
328 Comparison of Characters and Strings
329 ====================================
331 - Function: char-equal character1 character2 &optional buffer
332 This function returns `t' if the arguments represent the same
333 character, `nil' otherwise. This function ignores differences in
334 case if the value of `case-fold-search' is non-`nil' in BUFFER,
335 which defaults to the current buffer.
339 (let ((case-fold-search t))
342 (let ((case-fold-search nil))
346 - Function: char= character1 character2
347 This function returns `t' if the arguments represent the same
348 character, `nil' otherwise. Case is significant.
354 (let ((case-fold-search t))
357 (let ((case-fold-search nil))
361 - Function: string= string1 string2
362 This function returns `t' if the characters of the two strings
363 match exactly; case is significant.
365 (string= "abc" "abc")
367 (string= "abc" "ABC")
373 - Function: string-equal string1 string2
374 `string-equal' is another name for `string='.
376 - Function: string< string1 string2
377 This function compares two strings a character at a time. First it
378 scans both the strings at once to find the first pair of
379 corresponding characters that do not match. If the lesser
380 character of those two is the character from STRING1, then STRING1
381 is less, and this function returns `t'. If the lesser character
382 is the one from STRING2, then STRING1 is greater, and this
383 function returns `nil'. If the two strings match entirely, the
386 Pairs of characters are compared by their ASCII codes. Keep in
387 mind that lower case letters have higher numeric values in the
388 ASCII character set than their upper case counterparts; numbers and
389 many punctuation characters have a lower numeric value than upper
392 (string< "abc" "abd")
394 (string< "abd" "abc")
396 (string< "123" "abc")
399 When the strings have different lengths, and they match up to the
400 length of STRING1, then the result is `t'. If they match up to
401 the length of STRING2, the result is `nil'. A string of no
402 characters is less than any other string.
415 - Function: string-lessp string1 string2
416 `string-lessp' is another name for `string<'.
418 See also `compare-buffer-substrings' in *Note Comparing Text::, for
419 a way to compare text in buffers. The function `string-match', which
420 matches a regular expression against a string, can be used for a kind
421 of string comparison; see *Note Regexp Search::.
424 File: lispref.info, Node: String Conversion, Next: Modifying Strings, Prev: Text Comparison, Up: Strings and Characters
426 Conversion of Characters and Strings
427 ====================================
429 This section describes functions for conversions between characters,
430 strings and integers. `format' and `prin1-to-string' (*note Output
431 Functions::) can also convert Lisp objects into strings.
432 `read-from-string' (*note Input Functions::) can "convert" a string
433 representation of a Lisp object into an object.
435 *Note Documentation::, for functions that produce textual
436 descriptions of text characters and general input events
437 (`single-key-description' and `text-char-description'). These
438 functions are used primarily for making help messages.
440 - Function: char-to-string character
441 This function returns a new string with a length of one character.
442 The value of CHARACTER, modulo 256, is used to initialize the
443 element of the string.
445 This function is similar to `make-string' with an integer argument
446 of 1. (*Note Creating Strings::.) This conversion can also be
447 done with `format' using the `%c' format specification. (*Note
448 Formatting Strings::.)
452 (char-to-string (+ 256 ?x))
457 - Function: string-to-char string
458 This function returns the first character in STRING. If the
459 string is empty, the function returns 0. (Under XEmacs 19, the
460 value is also 0 when the first character of STRING is the null
461 character, ASCII code 0.)
463 (string-to-char "ABC")
464 => ?A ;; Under XEmacs 20.
465 => 65 ;; Under XEmacs 19.
466 (string-to-char "xyz")
467 => ?x ;; Under XEmacs 20.
468 => 120 ;; Under XEmacs 19.
471 (string-to-char "\000")
472 => ?\^ ;; Under XEmacs 20.
473 => 0 ;; Under XEmacs 20.
475 This function may be eliminated in the future if it does not seem
476 useful enough to retain.
478 - Function: number-to-string number
479 This function returns a string consisting of the printed
480 representation of NUMBER, which may be an integer or a floating
481 point number. The value starts with a sign if the argument is
484 (number-to-string 256)
486 (number-to-string -23)
488 (number-to-string -23.5)
491 `int-to-string' is a semi-obsolete alias for this function.
493 See also the function `format' in *Note Formatting Strings::.
495 - Function: string-to-number string &optional base
496 This function returns the numeric value represented by STRING,
497 read in BASE. It skips spaces and tabs at the beginning of
498 STRING, then reads as much of STRING as it can interpret as a
499 number. (On some systems it ignores other whitespace at the
500 beginning, not just spaces and tabs.) If the first character
501 after the ignored whitespace is not a digit or a minus sign, this
504 If BASE is not specified, it defaults to ten. With BASE other
505 than ten, only integers can be read.
507 (string-to-number "256")
509 (string-to-number "25 is a perfect square.")
511 (string-to-number "X256")
513 (string-to-number "-4.5")
515 (string-to-number "ffff" 16)
518 `string-to-int' is an obsolete alias for this function.
521 File: lispref.info, Node: Modifying Strings, Next: String Properties, Prev: String Conversion, Up: Strings and Characters
526 You can modify a string using the general array-modifying primitives.
527 *Note Arrays::. The function `aset' modifies a single character; the
528 function `fillarray' sets all characters in the string to a specified
531 Each string has a tick counter that starts out at zero (when the
532 string is created) and is incremented each time a change is made to that
535 - Function: string-modified-tick string
536 This function returns the tick counter for `string'.
539 File: lispref.info, Node: String Properties, Next: Formatting Strings, Prev: Modifying Strings, Up: Strings and Characters
544 Just as with symbols, extents, faces, and glyphs, you can attach
545 additional information to strings in the form of "string properties".
546 These differ from text properties, which are logically attached to
547 particular characters in the string.
549 To attach a property to a string, use `put'. To retrieve a property
550 from a string, use `get'. You can also use `remprop' to remove a
551 property from a string and `object-plist' to retrieve a list of all the
552 properties in a string.
555 File: lispref.info, Node: Formatting Strings, Next: Character Case, Prev: String Properties, Up: Strings and Characters
560 "Formatting" means constructing a string by substitution of computed
561 values at various places in a constant string. This string controls
562 how the other values are printed as well as where they appear; it is
563 called a "format string".
565 Formatting is often useful for computing messages to be displayed.
566 In fact, the functions `message' and `error' provide the same
567 formatting feature described here; they differ from `format' only in
568 how they use the result of formatting.
570 - Function: format string &rest objects
571 This function returns a new string that is made by copying STRING
572 and then replacing any format specification in the copy with
573 encodings of the corresponding OBJECTS. The arguments OBJECTS are
574 the computed values to be formatted.
576 A format specification is a sequence of characters beginning with a
577 `%'. Thus, if there is a `%d' in STRING, the `format' function
578 replaces it with the printed representation of one of the values to be
579 formatted (one of the arguments OBJECTS). For example:
581 (format "The value of fill-column is %d." fill-column)
582 => "The value of fill-column is 72."
584 If STRING contains more than one format specification, the format
585 specifications correspond with successive values from OBJECTS. Thus,
586 the first format specification in STRING uses the first such value, the
587 second format specification uses the second such value, and so on. Any
588 extra format specifications (those for which there are no corresponding
589 values) cause unpredictable behavior. Any extra values to be formatted
592 Certain format specifications require values of particular types.
593 However, no error is signaled if the value actually supplied fails to
594 have the expected type. Instead, the output is likely to be
597 Here is a table of valid format specifications:
600 Replace the specification with the printed representation of the
601 object, made without quoting. Thus, strings are represented by
602 their contents alone, with no `"' characters, and symbols appear
603 without `\' characters. This is equivalent to printing the object
606 If there is no corresponding object, the empty string is used.
609 Replace the specification with the printed representation of the
610 object, made with quoting. Thus, strings are enclosed in `"'
611 characters, and `\' characters appear where necessary before
612 special characters. This is equivalent to printing the object
615 If there is no corresponding object, the empty string is used.
618 Replace the specification with the base-eight representation of an
623 Replace the specification with the base-ten representation of an
627 Replace the specification with the base-sixteen representation of
628 an integer, using lowercase letters.
631 Replace the specification with the base-sixteen representation of
632 an integer, using uppercase letters.
635 Replace the specification with the character which is the value
639 Replace the specification with the exponential notation for a
640 floating point number (e.g. `7.85200e+03').
643 Replace the specification with the decimal-point notation for a
644 floating point number.
647 Replace the specification with notation for a floating point
648 number, using a "pretty format". Either exponential notation or
649 decimal-point notation will be used (usually whichever is
650 shorter), and trailing zeroes are removed from the fractional part.
653 A single `%' is placed in the string. This format specification is
654 unusual in that it does not use a value. For example, `(format "%%
655 %d" 30)' returns `"% 30"'.
657 Any other format character results in an `Invalid format operation'
660 Here are several examples:
662 (format "The name of this buffer is %s." (buffer-name))
663 => "The name of this buffer is strings.texi."
665 (format "The buffer object prints as %s." (current-buffer))
666 => "The buffer object prints as #<buffer strings.texi>."
668 (format "The octal value of %d is %o,
669 and the hex value is %x." 18 18 18)
670 => "The octal value of 18 is 22,
671 and the hex value is 12."
673 There are many additional flags and specifications that can occur
674 between the `%' and the format character, in the following order:
676 1. An optional repositioning specification, which is a positive
677 integer followed by a `$'.
679 2. Zero or more of the optional flag characters `-', `+', ` ', `0',
682 3. An asterisk (`*', meaning that the field width is now assumed to
683 have been specified as an argument.
685 4. An optional minimum field width.
687 5. An optional precision, preceded by a `.' character.
689 A "repositioning" specification changes which argument to `format'
690 is used by the current and all following format specifications.
691 Normally the first specification uses the first argument, the second
692 specification uses the second argument, etc. Using a repositioning
693 specification, you can change this. By placing a number N followed by
694 a `$' between the `%' and the format character, you cause the
695 specification to use the Nth argument. The next specification will use
696 the N+1'th argument, etc.
700 (format "Can't find file `%s' in directory `%s'."
701 "ignatius.c" "loyola/")
702 => "Can't find file `ignatius.c' in directory `loyola/'."
704 (format "In directory `%2$s', the file `%1$s' was not found."
705 "ignatius.c" "loyola/")
706 => "In directory `loyola/', the file `ignatius.c' was not found."
709 "The numbers %d and %d are %1$x and %x in hex and %1$o and %o in octal."
711 => "The numbers 37 and 12 are 25 and c in hex and 45 and 14 in octal."
713 As you can see, this lets you reprocess arguments more than once or
714 reword a format specification (thereby moving the arguments around)
715 without having to actually reorder the arguments. This is especially
716 useful in translating messages from one language to another: Different
717 languages use different word orders, and this sometimes entails changing
718 the order of the arguments. By using repositioning specifications,
719 this can be accomplished without having to embed knowledge of particular
720 languages into the location in the program's code where the message is
723 All the specification characters allow an optional numeric prefix
724 between the `%' and the character, and following any repositioning
725 specification or flag. The optional numeric prefix defines the minimum
726 width for the object. If the printed representation of the object
727 contains fewer characters than this, then it is padded. The padding is
728 normally on the left, but will be on the right if the `-' flag
729 character is given. The padding character is normally a space, but if
730 the `0' flag character is given, zeros are used for padding.
732 (format "%06d is padded on the left with zeros" 123)
733 => "000123 is padded on the left with zeros"
735 (format "%-6d is padded on the right" 123)
736 => "123 is padded on the right"
738 `format' never truncates an object's printed representation, no
739 matter what width you specify. Thus, you can use a numeric prefix to
740 specify a minimum spacing between columns with no risk of losing
743 In the following three examples, `%7s' specifies a minimum width of
744 7. In the first case, the string inserted in place of `%7s' has only 3
745 letters, so 4 blank spaces are inserted for padding. In the second
746 case, the string `"specification"' is 13 letters wide but is not
747 truncated. In the third case, the padding is on the right.
749 (format "The word `%7s' actually has %d letters in it."
750 "foo" (length "foo"))
751 => "The word ` foo' actually has 3 letters in it."
753 (format "The word `%7s' actually has %d letters in it."
754 "specification" (length "specification"))
755 => "The word `specification' actually has 13 letters in it."
757 (format "The word `%-7s' actually has %d letters in it."
758 "foo" (length "foo"))
759 => "The word `foo ' actually has 3 letters in it."
761 After any minimum field width, a precision may be specified by
762 preceding it with a `.' character. The precision specifies the minimum
763 number of digits to appear in `%d', `%i', `%o', `%x', and `%X'
764 conversions (the number is padded on the left with zeroes as
765 necessary); the number of digits printed after the decimal point for
766 `%f', `%e', and `%E' conversions; the number of significant digits
767 printed in `%g' and `%G' conversions; and the maximum number of
768 non-padding characters printed in `%s' and `%S' conversions. The
769 default precision for floating-point conversions is six.
771 The other flag characters have the following meanings:
773 * The ` ' flag means prefix non-negative numbers with a space.
775 * The `+' flag means prefix non-negative numbers with a plus sign.
777 * The `#' flag means print numbers in an alternate, more verbose
778 format: octal numbers begin with zero; hex numbers begin with a
779 `0x' or `0X'; a decimal point is printed in `%f', `%e', and `%E'
780 conversions even if no numbers are printed after it; and trailing
781 zeroes are not omitted in `%g' and `%G' conversions.
784 File: lispref.info, Node: Character Case, Next: Case Tables, Prev: Formatting Strings, Up: Strings and Characters
789 The character case functions change the case of single characters or
790 of the contents of strings. The functions convert only alphabetic
791 characters (the letters `A' through `Z' and `a' through `z'); other
792 characters are not altered. The functions do not modify the strings
793 that are passed to them as arguments.
795 The examples below use the characters `X' and `x' which have ASCII
796 codes 88 and 120 respectively.
798 - Function: downcase string-or-char &optional buffer
799 This function converts a character or a string to lower case.
801 When the argument to `downcase' is a string, the function creates
802 and returns a new string in which each letter in the argument that
803 is upper case is converted to lower case. When the argument to
804 `downcase' is a character, `downcase' returns the corresponding
805 lower case character. (This value is actually an integer under
806 XEmacs 19.) If the original character is lower case, or is not a
807 letter, then the value equals the original character.
809 Optional second arg BUFFER specifies which buffer's case tables to
810 use, and defaults to the current buffer.
812 (downcase "The cat in the hat")
813 => "the cat in the hat"
816 => ?x ;; Under XEmacs 20.
817 => 120 ;; Under XEmacs 19.
819 - Function: upcase string-or-char &optional buffer
820 This function converts a character or a string to upper case.
822 When the argument to `upcase' is a string, the function creates
823 and returns a new string in which each letter in the argument that
824 is lower case is converted to upper case.
826 When the argument to `upcase' is a character, `upcase' returns the
827 corresponding upper case character. (This value is actually an
828 integer under XEmacs 19.) If the original character is upper
829 case, or is not a letter, then the value equals the original
832 Optional second arg BUFFER specifies which buffer's case tables to
833 use, and defaults to the current buffer.
835 (upcase "The cat in the hat")
836 => "THE CAT IN THE HAT"
839 => ?X ;; Under XEmacs 20.
840 => 88 ;; Under XEmacs 19.
842 - Function: capitalize string-or-char &optional buffer
843 This function capitalizes strings or characters. If
844 STRING-OR-CHAR is a string, the function creates and returns a new
845 string, whose contents are a copy of STRING-OR-CHAR in which each
846 word has been capitalized. This means that the first character of
847 each word is converted to upper case, and the rest are converted
850 The definition of a word is any sequence of consecutive characters
851 that are assigned to the word constituent syntax class in the
852 current syntax table (*note Syntax Class Table::).
854 When the argument to `capitalize' is a character, `capitalize' has
855 the same result as `upcase'.
857 Optional second arg BUFFER specifies which buffer's case tables to
858 use, and defaults to the current buffer.
860 (capitalize "The cat in the hat")
861 => "The Cat In The Hat"
863 (capitalize "THE 77TH-HATTED CAT")
864 => "The 77th-Hatted Cat"
867 => ?X ;; Under XEmacs 20.
868 => 88 ;; Under XEmacs 19.
871 File: lispref.info, Node: Case Tables, Next: Char Tables, Prev: Character Case, Up: Strings and Characters
876 You can customize case conversion by installing a special "case
877 table". A case table specifies the mapping between upper case and lower
878 case letters. It affects both the string and character case conversion
879 functions (see the previous section) and those that apply to text in the
880 buffer (*note Case Changes::). You need a case table if you are using a
881 language which has letters other than the standard ASCII letters.
883 A case table is a list of this form:
885 (DOWNCASE UPCASE CANONICALIZE EQUIVALENCES)
887 where each element is either `nil' or a string of length 256. The
888 element DOWNCASE says how to map each character to its lower-case
889 equivalent. The element UPCASE maps each character to its upper-case
890 equivalent. If lower and upper case characters are in one-to-one
891 correspondence, use `nil' for UPCASE; then XEmacs deduces the upcase
894 For some languages, upper and lower case letters are not in
895 one-to-one correspondence. There may be two different lower case
896 letters with the same upper case equivalent. In these cases, you need
897 to specify the maps for both directions.
899 The element CANONICALIZE maps each character to a canonical
900 equivalent; any two characters that are related by case-conversion have
901 the same canonical equivalent character.
903 The element EQUIVALENCES is a map that cyclicly permutes each
904 equivalence class (of characters with the same canonical equivalent).
905 (For ordinary ASCII, this would map `a' into `A' and `A' into `a', and
906 likewise for each set of equivalent characters.)
908 When you construct a case table, you can provide `nil' for
909 CANONICALIZE; then Emacs fills in this string from UPCASE and DOWNCASE.
910 You can also provide `nil' for EQUIVALENCES; then Emacs fills in this
911 string from CANONICALIZE. In a case table that is actually in use,
912 those components are non-`nil'. Do not try to specify EQUIVALENCES
913 without also specifying CANONICALIZE.
915 Each buffer has a case table. XEmacs also has a "standard case
916 table" which is copied into each buffer when you create the buffer.
917 Changing the standard case table doesn't affect any existing buffers.
919 Here are the functions for working with case tables:
921 - Function: case-table-p object
922 This predicate returns non-`nil' if OBJECT is a valid case table.
924 - Function: set-standard-case-table case-table
925 This function makes CASE-TABLE the standard case table, so that it
926 will apply to any buffers created subsequently.
928 - Function: standard-case-table
929 This returns the standard case table.
931 - Function: current-case-table &optional buffer
932 This function returns the case table of BUFFER, which defaults to
935 - Function: set-case-table case-table
936 This sets the current buffer's case table to CASE-TABLE.
938 The following three functions are convenient subroutines for packages
939 that define non-ASCII character sets. They modify a string
940 DOWNCASE-TABLE provided as an argument; this should be a string to be
941 used as the DOWNCASE part of a case table. They also modify the
942 standard syntax table. *Note Syntax Tables::.
944 - Function: set-case-syntax-pair uc lc downcase-table
945 This function specifies a pair of corresponding letters, one upper
946 case and one lower case.
948 - Function: set-case-syntax-delims l r downcase-table
949 This function makes characters L and R a matching pair of
950 case-invariant delimiters.
952 - Function: set-case-syntax char syntax downcase-table
953 This function makes CHAR case-invariant, with syntax SYNTAX.
955 - Command: describe-buffer-case-table
956 This command displays a description of the contents of the current
959 You can load the library `iso-syntax' to set up the standard syntax
960 table and define a case table for the 8-bit ISO Latin 1 character set.
963 File: lispref.info, Node: Char Tables, Prev: Case Tables, Up: Strings and Characters
968 A char table is a table that maps characters (or ranges of
969 characters) to values. Char tables are specialized for characters,
970 only allowing particular sorts of ranges to be assigned values.
971 Although this loses in generality, it makes for extremely fast
972 (constant-time) lookups, and thus is feasible for applications that do
973 an extremely large number of lookups (e.g. scanning a buffer for a
974 character in a particular syntax, where a lookup in the syntax table
975 must occur once per character).
977 Note that char tables as a primitive type, and all of the functions
978 in this section, exist only in XEmacs 20. In XEmacs 19, char tables are
979 generally implemented using a vector of 256 elements.
981 When MULE support exists, the types of ranges that can be assigned
988 * a single row in a two-octet charset
992 When MULE support is not present, the types of ranges that can be
999 - Function: char-table-p object
1000 This function returns non-`nil' if OBJECT is a char table.
1004 * Char Table Types:: Char tables have different uses.
1005 * Working With Char Tables:: Creating and working with char tables.
1008 File: lispref.info, Node: Char Table Types, Next: Working With Char Tables, Up: Char Tables
1013 Each char table type is used for a different purpose and allows
1014 different sorts of values. The different char table types are
1017 Used for category tables, which specify the regexp categories that
1018 a character is in. The valid values are `nil' or a bit vector of
1019 95 elements. Higher-level Lisp functions are provided for working
1020 with category tables. Currently categories and category tables
1021 only exist when MULE support is present.
1024 A generalized char table, for mapping from one character to
1025 another. Used for case tables, syntax matching tables,
1026 `keyboard-translate-table', etc. The valid values are characters.
1029 An even more generalized char table, for mapping from a character
1033 Used for display tables, which specify how a particular character
1034 is to appear when displayed. #### Not yet implemented.
1037 Used for syntax tables, which specify the syntax of a particular
1038 character. Higher-level Lisp functions are provided for working
1039 with syntax tables. The valid values are integers.
1041 - Function: char-table-type char-table
1042 This function returns the type of char table CHAR-TABLE.
1044 - Function: char-table-type-list
1045 This function returns a list of the recognized char table types.
1047 - Function: valid-char-table-type-p type
1048 This function returns `t' if TYPE if a recognized char table type.
1051 File: lispref.info, Node: Working With Char Tables, Prev: Char Table Types, Up: Char Tables
1053 Working With Char Tables
1054 ------------------------
1056 - Function: make-char-table type
1057 This function makes a new, empty char table of type TYPE. TYPE
1058 should be a symbol, one of `char', `category', `display',
1059 `generic', or `syntax'.
1061 - Function: put-char-table range value char-table
1062 This function sets the value for chars in RANGE to be VALUE in
1065 RANGE specifies one or more characters to be affected and should be
1066 one of the following:
1068 * `t' (all characters are affected)
1070 * A charset (only allowed when MULE support is present)
1072 * A vector of two elements: a two-octet charset and a row number
1073 (only allowed when MULE support is present)
1075 * A single character
1077 VALUE must be a value appropriate for the type of CHAR-TABLE.
1079 - Function: get-char-table character char-table
1080 This function finds the value for CHARACTER in CHAR-TABLE.
1082 - Function: get-range-char-table range char-table &optional multi
1083 This function finds the value for a range in CHAR-TABLE. If there
1084 is more than one value, MULTI is returned (defaults to `nil').
1086 - Function: reset-char-table char-table
1087 This function resets CHAR-TABLE to its default state.
1089 - Function: map-char-table function char-table &optional range
1090 This function maps FUNCTION over entries in CHAR-TABLE, calling it
1091 with two args, each key and value in the table.
1093 RANGE specifies a subrange to map over and is in the same format
1094 as the RANGE argument to `put-range-table'. If omitted or `t', it
1095 defaults to the entire table.
1097 - Function: valid-char-table-value-p value char-table-type
1098 This function returns non-`nil' if VALUE is a valid value for
1101 - Function: check-valid-char-table-value value char-table-type
1102 This function signals an error if VALUE is not a valid value for
1106 File: lispref.info, Node: Lists, Next: Sequences Arrays Vectors, Prev: Strings and Characters, Up: Top
1111 A "list" represents a sequence of zero or more elements (which may
1112 be any Lisp objects). The important difference between lists and
1113 vectors is that two or more lists can share part of their structure; in
1114 addition, you can insert or delete elements in a list without copying
1119 * Cons Cells:: How lists are made out of cons cells.
1120 * Lists as Boxes:: Graphical notation to explain lists.
1121 * List-related Predicates:: Is this object a list? Comparing two lists.
1122 * List Elements:: Extracting the pieces of a list.
1123 * Building Lists:: Creating list structure.
1124 * Modifying Lists:: Storing new pieces into an existing list.
1125 * Sets And Lists:: A list can represent a finite mathematical set.
1126 * Association Lists:: A list can represent a finite relation or mapping.
1127 * Property Lists:: A different way to represent a finite mapping.
1128 * Weak Lists:: A list with special garbage-collection behavior.
1131 File: lispref.info, Node: Cons Cells, Next: Lists as Boxes, Up: Lists
1133 Lists and Cons Cells
1134 ====================
1136 Lists in Lisp are not a primitive data type; they are built up from
1137 "cons cells". A cons cell is a data object that represents an ordered
1138 pair. It records two Lisp objects, one labeled as the CAR, and the
1139 other labeled as the CDR. These names are traditional; see *Note Cons
1140 Cell Type::. CDR is pronounced "could-er."
1142 A list is a series of cons cells chained together, one cons cell per
1143 element of the list. By convention, the CARs of the cons cells are the
1144 elements of the list, and the CDRs are used to chain the list: the CDR
1145 of each cons cell is the following cons cell. The CDR of the last cons
1146 cell is `nil'. This asymmetry between the CAR and the CDR is entirely
1147 a matter of convention; at the level of cons cells, the CAR and CDR
1148 slots have the same characteristics.
1150 Because most cons cells are used as part of lists, the phrase "list
1151 structure" has come to mean any structure made out of cons cells.
1153 The symbol `nil' is considered a list as well as a symbol; it is the
1154 list with no elements. For convenience, the symbol `nil' is considered
1155 to have `nil' as its CDR (and also as its CAR).
1157 The CDR of any nonempty list L is a list containing all the elements
1158 of L except the first.
1161 File: lispref.info, Node: Lists as Boxes, Next: List-related Predicates, Prev: Cons Cells, Up: Lists
1163 Lists as Linked Pairs of Boxes
1164 ==============================
1166 A cons cell can be illustrated as a pair of boxes. The first box
1167 represents the CAR and the second box represents the CDR. Here is an
1168 illustration of the two-element list, `(tulip lily)', made from two
1171 --------------- ---------------
1172 | car | cdr | | car | cdr |
1173 | tulip | o---------->| lily | nil |
1175 --------------- ---------------
1177 Each pair of boxes represents a cons cell. Each box "refers to",
1178 "points to" or "contains" a Lisp object. (These terms are synonymous.)
1179 The first box, which is the CAR of the first cons cell, contains the
1180 symbol `tulip'. The arrow from the CDR of the first cons cell to the
1181 second cons cell indicates that the CDR of the first cons cell points
1182 to the second cons cell.
1184 The same list can be illustrated in a different sort of box notation
1188 |___|___|--> |___|___|--> nil
1193 Here is a more complex illustration, showing the three-element list,
1194 `((pine needles) oak maple)', the first element of which is a
1197 ___ ___ ___ ___ ___ ___
1198 |___|___|--> |___|___|--> |___|___|--> nil
1204 --> |___|___|--> |___|___|--> nil
1207 --> pine --> needles
1209 The same list represented in the first box notation looks like this:
1211 -------------- -------------- --------------
1212 | car | cdr | | car | cdr | | car | cdr |
1213 | o | o------->| oak | o------->| maple | nil |
1215 -- | --------- -------------- --------------
1218 | -------------- ----------------
1219 | | car | cdr | | car | cdr |
1220 ------>| pine | o------->| needles | nil |
1222 -------------- ----------------
1224 *Note Cons Cell Type::, for the read and print syntax of cons cells
1225 and lists, and for more "box and arrow" illustrations of lists.
1228 File: lispref.info, Node: List-related Predicates, Next: List Elements, Prev: Lists as Boxes, Up: Lists
1233 The following predicates test whether a Lisp object is an atom, is a
1234 cons cell or is a list, or whether it is the distinguished object
1235 `nil'. (Many of these predicates can be defined in terms of the
1236 others, but they are used so often that it is worth having all of them.)
1238 - Function: consp object
1239 This function returns `t' if OBJECT is a cons cell, `nil'
1240 otherwise. `nil' is not a cons cell, although it _is_ a list.
1242 - Function: atom object
1243 This function returns `t' if OBJECT is an atom, `nil' otherwise.
1244 All objects except cons cells are atoms. The symbol `nil' is an
1245 atom and is also a list; it is the only Lisp object that is both.
1247 (atom OBJECT) == (not (consp OBJECT))
1249 - Function: listp object
1250 This function returns `t' if OBJECT is a cons cell or `nil'.
1251 Otherwise, it returns `nil'.
1258 - Function: nlistp object
1259 This function is the opposite of `listp': it returns `t' if OBJECT
1260 is not a list. Otherwise, it returns `nil'.
1262 (listp OBJECT) == (not (nlistp OBJECT))
1264 - Function: null object
1265 This function returns `t' if OBJECT is `nil', and returns `nil'
1266 otherwise. This function is identical to `not', but as a matter
1267 of clarity we use `null' when OBJECT is considered a list and
1268 `not' when it is considered a truth value (see `not' in *Note
1269 Combining Conditions::).