This is Info file elisp, produced by Makeinfo version 1.68 from the input file elisp.texi. INFO-DIR-SECTION Editors START-INFO-DIR-ENTRY * Elisp: (elisp). The Emacs Lisp Reference Manual. END-INFO-DIR-ENTRY This version is the edition 2.5 of the GNU Emacs Lisp Reference Manual. It corresponds to Emacs Version 20.3 Published by the Free Software Foundation 59 Temple Place, Suite 330 Boston, MA 02111-1307 USA Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the Free Software Foundation instead of in the original English.  File: elisp, Node: Creating Strings, Next: Modifying Strings, Prev: Predicates for Strings, Up: Strings and Characters Creating Strings ================ The following functions create strings, either from scratch, or by putting strings together, or by taking them apart. - Function: make-string COUNT CHARACTER This function returns a string made up of COUNT repetitions of CHARACTER. If COUNT is negative, an error is signaled. (make-string 5 ?x) => "xxxxx" (make-string 0 ?x) => "" Other functions to compare with this one include `char-to-string' (*note String Conversion::.), `make-vector' (*note Vectors::.), and `make-list' (*note Building Lists::.). - Function: string &rest CHARACTERS This returns a string containing the characters CHARACTERS. (string ?a ?b ?c) => "abc" - Function: substring STRING START &optional END This function returns a new string which consists of those characters from STRING in the range from (and including) the character at the index START up to (but excluding) the character at the index END. The first character is at index zero. (substring "abcdefg" 0 3) => "abc" Here the index for `a' is 0, the index for `b' is 1, and the index for `c' is 2. Thus, three letters, `abc', are copied from the string `"abcdefg"'. The index 3 marks the character position up to which the substring is copied. The character whose index is 3 is actually the fourth character in the string. A negative number counts from the end of the string, so that -1 signifies the index of the last character of the string. For example: (substring "abcdefg" -3 -1) => "ef" In this example, the index for `e' is -3, the index for `f' is -2, and the index for `g' is -1. Therefore, `e' and `f' are included, and `g' is excluded. When `nil' is used as an index, it stands for the length of the string. Thus, (substring "abcdefg" -3 nil) => "efg" Omitting the argument END is equivalent to specifying `nil'. It follows that `(substring STRING 0)' returns a copy of all of STRING. (substring "abcdefg" 0) => "abcdefg" But we recommend `copy-sequence' for this purpose (*note Sequence Functions::.). If the characters copied from STRING have text properties, the properties are copied into the new string also. *Note Text Properties::. `substring' also allows vectors for the first argument. For example: (substring [a b (c) "d"] 1 3) => [b (c)] A `wrong-type-argument' error is signaled if either START or END is not an integer or `nil'. An `args-out-of-range' error is signaled if START indicates a character following END, or if either integer is out of range for STRING. Contrast this function with `buffer-substring' (*note Buffer Contents::.), which returns a string containing a portion of the text in the current buffer. The beginning of a string is at index 0, but the beginning of a buffer is at index 1. - Function: concat &rest SEQUENCES This function returns a new string consisting of the characters in the arguments passed to it (along with their text properties, if any). The arguments may be strings, lists of numbers, or vectors of numbers; they are not themselves changed. If `concat' receives no arguments, it returns an empty string. (concat "abc" "-def") => "abc-def" (concat "abc" (list 120 121) [122]) => "abcxyz" ;; `nil' is an empty sequence. (concat "abc" nil "-def") => "abc-def" (concat "The " "quick brown " "fox.") => "The quick brown fox." (concat) => "" The `concat' function always constructs a new string that is not `eq' to any existing string. When an argument is an integer (not a sequence of integers), it is converted to a string of digits making up the decimal printed representation of the integer. *Don't use this feature; we plan to eliminate it. If you already use this feature, change your programs now!* The proper way to convert an integer to a decimal number in this way is with `format' (*note Formatting Strings::.) or `number-to-string' (*note String Conversion::.). (concat 137) => "137" (concat 54 321) => "54321" For information about other concatenation functions, see the description of `mapconcat' in *Note Mapping Functions::, `vconcat' in *Note Vectors::, and `append' in *Note Building Lists::. - Function: split-string STRING SEPARATORS Split STRING into substrings in between matches for the regular expression SEPARATORS. Each match for SEPARATORS defines a splitting point; the substrings between the splitting points are made into a list, which is the value. If SEPARATORS is `nil' (or omitted), the default is `"[ \f\t\n\r\v]+"'. For example, (split-string "Soup is good food" "o") => ("S" "up is g" "" "d f" "" "d") (split-string "Soup is good food" "o+") => ("S" "up is g" "d f" "d") When there is a match adjacent to the beginning or end of the string, this does not cause a null string to appear at the beginning or end of the list: (split-string "out to moo" "o+") => ("ut t" " m") Empty matches do count, when not adjacent to another match: (split-string "Soup is good food" "o*") =>("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d") (split-string "Nice doggy!" "") =>("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!")  File: elisp, Node: Modifying Strings, Next: Text Comparison, Prev: Creating Strings, Up: Strings and Characters Modifying Strings ================= The most basic way to alter the contents of an existing string is with `aset' (*note Array Functions::.). `(aset STRING IDX CHAR)' stores CHAR into STRING at index IDX. Each character occupies one or more bytes, and if CHAR needs a different number of bytes from the character already present at that index, `aset' signals an error. A more powerful function is `store-substring': - Function: store-substring STRING IDX OBJ This function alters part of the contents of the string STRING, by storing OBJ starting at index IDX. The argument OBJ may be either a character or a (smaller) string. Since it is impossible to change the length of an existing string, it is an error if OBJ doesn't fit within STRING's actual length, of if any new character requires a different number of bytes from the character currently present at that point in STRING.  File: elisp, Node: Text Comparison, Next: String Conversion, Prev: Modifying Strings, Up: Strings and Characters Comparison of Characters and Strings ==================================== - Function: char-equal CHARACTER1 CHARACTER2 This function returns `t' if the arguments represent the same character, `nil' otherwise. This function ignores differences in case if `case-fold-search' is non-`nil'. (char-equal ?x ?x) => t (let ((case-fold-search nil)) (char-equal ?x ?X)) => nil - Function: string= STRING1 STRING2 This function returns `t' if the characters of the two strings match exactly; case is significant. (string= "abc" "abc") => t (string= "abc" "ABC") => nil (string= "ab" "ABC") => nil The function `string=' ignores the text properties of the two strings. When `equal' (*note Equality Predicates::.) compares two strings, it uses `string='. If the strings contain non-ASCII characters, and one is unibyte while the other is multibyte, then they cannot be equal. *Note Text Representations::. - Function: string-equal STRING1 STRING2 `string-equal' is another name for `string='. - Function: string< STRING1 STRING2 This function compares two strings a character at a time. First it scans both the strings at once to find the first pair of corresponding characters that do not match. If the lesser character of those two is the character from STRING1, then STRING1 is less, and this function returns `t'. If the lesser character is the one from STRING2, then STRING1 is greater, and this function returns `nil'. If the two strings match entirely, the value is `nil'. Pairs of characters are compared according to their character codes. Keep in mind that lower case letters have higher numeric values in the ASCII character set than their upper case counterparts; digits and many punctuation characters have a lower numeric value than upper case letters. An ASCII character is less than any non-ASCII character; a unibyte non-ASCII character is always less than any multibyte non-ASCII character (*note Text Representations::.). (string< "abc" "abd") => t (string< "abd" "abc") => nil (string< "123" "abc") => t When the strings have different lengths, and they match up to the length of STRING1, then the result is `t'. If they match up to the length of STRING2, the result is `nil'. A string of no characters is less than any other string. (string< "" "abc") => t (string< "ab" "abc") => t (string< "abc" "") => nil (string< "abc" "ab") => nil (string< "" "") => nil - Function: string-lessp STRING1 STRING2 `string-lessp' is another name for `string<'. - Function: compare-strings STRING1 START1 END1 STRING2 START2 END2 &optional IGNORE-CASE This function compares a specified part of STRING1 with a specified part of STRING2. The specified part of STRING1 runs from index START1 up to index END1 (default, the end of the string). The specified part of STRING2 runs from index START2 up to index END2 (default, the end of the string). The strings are both converted to multibyte for the comparison (*note Text Representations::.) so that a unibyte string can be equal to a multibyte string. If IGNORE-CASE is non-`nil', then case is ignored, so that upper case letters can be equal to lower case letters. If the specified portions of the two strings match, the value is `t'. Otherwise, the value is an integer which indicates how many leading characters agree, and which string is less. Its absolute value is one plus the number of characters that agree at the beginning of the two strings. The sign is negative if STRING1 (or its specified portion) is less. - Function: assoc-ignore-case KEY ALIST This function works like `assoc', except that KEY must be a string, and comparison is done using `compare-strings'. Case differences are ignored in this comparison. - Function: assoc-ignore-representation KEY ALIST This function works like `assoc', except that KEY must be a string, and comparison is done using `compare-strings'. Case differences are significant. See also `compare-buffer-substrings' in *Note Comparing Text::, for a way to compare text in buffers. The function `string-match', which matches a regular expression against a string, can be used for a kind of string comparison; see *Note Regexp Search::.  File: elisp, Node: String Conversion, Next: Formatting Strings, Prev: Text Comparison, Up: Strings and Characters Conversion of Characters and Strings ==================================== This section describes functions for conversions between characters, strings and integers. `format' and `prin1-to-string' (*note Output Functions::.) can also convert Lisp objects into strings. `read-from-string' (*note Input Functions::.) can "convert" a string representation of a Lisp object into an object. The functions `string-make-multibyte' and `string-make-unibyte' convert the text representation of a string (*note Converting Representations::.). *Note Documentation::, for functions that produce textual descriptions of text characters and general input events (`single-key-description' and `text-char-description'). These functions are used primarily for making help messages. - Function: char-to-string CHARACTER This function returns a new string containing one character, CHARACTER. This function is semi-obsolete because the function `string' is more general. *Note Creating Strings::. - Function: string-to-char STRING This function returns the first character in STRING. If the string is empty, the function returns 0. The value is also 0 when the first character of STRING is the null character, ASCII code 0. (string-to-char "ABC") => 65 (string-to-char "xyz") => 120 (string-to-char "") => 0 (string-to-char "\000") => 0 This function may be eliminated in the future if it does not seem useful enough to retain. - Function: number-to-string NUMBER This function returns a string consisting of the printed representation of NUMBER, which may be an integer or a floating point number. The value starts with a sign if the argument is negative. (number-to-string 256) => "256" (number-to-string -23) => "-23" (number-to-string -23.5) => "-23.5" `int-to-string' is a semi-obsolete alias for this function. See also the function `format' in *Note Formatting Strings::. - Function: string-to-number STRING &optional BASE This function returns the numeric value of the characters in STRING. If BASE is non-`nil', integers are converted in that base. If BASE is `nil', then base ten is used. Floating point conversion always uses base ten; we have not implemented other radices for floating point numbers, because that would be much more work and does not seem useful. The parsing skips spaces and tabs at the beginning of STRING, then reads as much of STRING as it can interpret as a number. (On some systems it ignores other whitespace at the beginning, not just spaces and tabs.) If the first character after the ignored whitespace is not a digit or a plus or minus sign, this function returns 0. (string-to-number "256") => 256 (string-to-number "25 is a perfect square.") => 25 (string-to-number "X256") => 0 (string-to-number "-4.5") => -4.5 `string-to-int' is an obsolete alias for this function. Here are some other functions that can convert to or from a string: `concat' `concat' can convert a vector or a list into a string. *Note Creating Strings::. `vconcat' `vconcat' can convert a string into a vector. *Note Vector Functions::. `append' `append' can convert a string into a list. *Note Building Lists::.  File: elisp, Node: Formatting Strings, Next: Case Conversion, Prev: String Conversion, Up: Strings and Characters Formatting Strings ================== "Formatting" means constructing a string by substitution of computed values at various places in a constant string. This string controls how the other values are printed as well as where they appear; it is called a "format string". Formatting is often useful for computing messages to be displayed. In fact, the functions `message' and `error' provide the same formatting feature described here; they differ from `format' only in how they use the result of formatting. - Function: format STRING &rest OBJECTS This function returns a new string that is made by copying STRING and then replacing any format specification in the copy with encodings of the corresponding OBJECTS. The arguments OBJECTS are the computed values to be formatted. A format specification is a sequence of characters beginning with a `%'. Thus, if there is a `%d' in STRING, the `format' function replaces it with the printed representation of one of the values to be formatted (one of the arguments OBJECTS). For example: (format "The value of fill-column is %d." fill-column) => "The value of fill-column is 72." If STRING contains more than one format specification, the format specifications correspond with successive values from OBJECTS. Thus, the first format specification in STRING uses the first such value, the second format specification uses the second such value, and so on. Any extra format specifications (those for which there are no corresponding values) cause unpredictable behavior. Any extra values to be formatted are ignored. Certain format specifications require values of particular types. If you supply a value that doesn't fit the requirements, an error is signaled. Here is a table of valid format specifications: `%s' Replace the specification with the printed representation of the object, made without quoting (that is, using `princ', not `prin1'--*note Output Functions::.). Thus, strings are represented by their contents alone, with no `"' characters, and symbols appear without `\' characters. If there is no corresponding object, the empty string is used. `%S' Replace the specification with the printed representation of the object, made with quoting (that is, using `prin1'--*note Output Functions::.). Thus, strings are enclosed in `"' characters, and `\' characters appear where necessary before special characters. If there is no corresponding object, the empty string is used. `%o' Replace the specification with the base-eight representation of an integer. `%d' Replace the specification with the base-ten representation of an integer. `%x' Replace the specification with the base-sixteen representation of an integer. `%c' Replace the specification with the character which is the value given. `%e' Replace the specification with the exponential notation for a floating point number. `%f' Replace the specification with the decimal-point notation for a floating point number. `%g' Replace the specification with notation for a floating point number, using either exponential notation or decimal-point notation, whichever is shorter. `%%' A single `%' is placed in the string. This format specification is unusual in that it does not use a value. For example, `(format "%% %d" 30)' returns `"% 30"'. Any other format character results in an `Invalid format operation' error. Here are several examples: (format "The name of this buffer is %s." (buffer-name)) => "The name of this buffer is strings.texi." (format "The buffer object prints as %s." (current-buffer)) => "The buffer object prints as strings.texi." (format "The octal value of %d is %o, and the hex value is %x." 18 18 18) => "The octal value of 18 is 22, and the hex value is 12." All the specification characters allow an optional numeric prefix between the `%' and the character. The optional numeric prefix defines the minimum width for the object. If the printed representation of the object contains fewer characters than this, then it is padded. The padding is on the left if the prefix is positive (or starts with zero) and on the right if the prefix is negative. The padding character is normally a space, but if the numeric prefix starts with a zero, zeros are used for padding. Here are some examples of padding: (format "%06d is padded on the left with zeros" 123) => "000123 is padded on the left with zeros" (format "%-6d is padded on the right" 123) => "123 is padded on the right" `format' never truncates an object's printed representation, no matter what width you specify. Thus, you can use a numeric prefix to specify a minimum spacing between columns with no risk of losing information. In the following three examples, `%7s' specifies a minimum width of 7. In the first case, the string inserted in place of `%7s' has only 3 letters, so 4 blank spaces are inserted for padding. In the second case, the string `"specification"' is 13 letters wide but is not truncated. In the third case, the padding is on the right. (format "The word `%7s' actually has %d letters in it." "foo" (length "foo")) => "The word ` foo' actually has 3 letters in it." (format "The word `%7s' actually has %d letters in it." "specification" (length "specification")) => "The word `specification' actually has 13 letters in it." (format "The word `%-7s' actually has %d letters in it." "foo" (length "foo")) => "The word `foo ' actually has 3 letters in it."  File: elisp, Node: Case Conversion, Next: Case Tables, Prev: Formatting Strings, Up: Strings and Characters Case Conversion in Lisp ======================= The character case functions change the case of single characters or of the contents of strings. The functions normally convert only alphabetic characters (the letters `A' through `Z' and `a' through `z', as well as non-ASCII letters); other characters are not altered. (You can specify a different case conversion mapping by specifying a case table--*note Case Tables::..) These functions do not modify the strings that are passed to them as arguments. The examples below use the characters `X' and `x' which have ASCII codes 88 and 120 respectively. - Function: downcase STRING-OR-CHAR This function converts a character or a string to lower case. When the argument to `downcase' is a string, the function creates and returns a new string in which each letter in the argument that is upper case is converted to lower case. When the argument to `downcase' is a character, `downcase' returns the corresponding lower case character. This value is an integer. If the original character is lower case, or is not a letter, then the value equals the original character. (downcase "The cat in the hat") => "the cat in the hat" (downcase ?X) => 120 - Function: upcase STRING-OR-CHAR This function converts a character or a string to upper case. When the argument to `upcase' is a string, the function creates and returns a new string in which each letter in the argument that is lower case is converted to upper case. When the argument to `upcase' is a character, `upcase' returns the corresponding upper case character. This value is an integer. If the original character is upper case, or is not a letter, then the value equals the original character. (upcase "The cat in the hat") => "THE CAT IN THE HAT" (upcase ?x) => 88 - Function: capitalize STRING-OR-CHAR This function capitalizes strings or characters. If STRING-OR-CHAR is a string, the function creates and returns a new string, whose contents are a copy of STRING-OR-CHAR in which each word has been capitalized. This means that the first character of each word is converted to upper case, and the rest are converted to lower case. The definition of a word is any sequence of consecutive characters that are assigned to the word constituent syntax class in the current syntax table (*Note Syntax Class Table::). When the argument to `capitalize' is a character, `capitalize' has the same result as `upcase'. (capitalize "The cat in the hat") => "The Cat In The Hat" (capitalize "THE 77TH-HATTED CAT") => "The 77th-Hatted Cat" (capitalize ?x) => 88 - Function: upcase-initials STRING This function capitalizes the initials of the words in STRING. without altering any letters other than the initials. It returns a new string whose contents are a copy of STRING, in which each word has been converted to upper case. The definition of a word is any sequence of consecutive characters that are assigned to the word constituent syntax class in the current syntax table (*Note Syntax Class Table::). (upcase-initials "The CAT in the hAt") => "The CAT In The HAt" *Note Text Comparison::, for functions that compare strings; some of them ignore case differences, or can optionally ignore case differences.  File: elisp, Node: Case Tables, Prev: Case Conversion, Up: Strings and Characters The Case Table ============== You can customize case conversion by installing a special "case table". A case table specifies the mapping between upper case and lower case letters. It affects both the case conversion functions for Lisp objects (see the previous section) and those that apply to text in the buffer (*note Case Changes::.). Each buffer has a case table; there is also a standard case table which is used to initialize the case table of new buffers. A case table is a char-table (*note Char-Tables::.) whose subtype is `case-table'. This char-table maps each character into the corresponding lower case character. It has three extra slots, which hold related tables: UPCASE The upcase table maps each character into the corresponding upper case character. CANONICALIZE The canonicalize table maps all of a set of case-related characters into a particular member of that set. EQUIVALENCES The equivalences table maps each one of a set of case-related characters into the next character in that set. In simple cases, all you need to specify is the mapping to lower-case; the three related tables will be calculated automatically from that one. For some languages, upper and lower case letters are not in one-to-one correspondence. There may be two different lower case letters with the same upper case equivalent. In these cases, you need to specify the maps for both lower case and upper case. The extra table CANONICALIZE maps each character to a canonical equivalent; any two characters that are related by case-conversion have the same canonical equivalent character. For example, since `a' and `A' are related by case-conversion, they should have the same canonical equivalent character (which should be either `a' for both of them, or `A' for both of them). The extra table EQUIVALENCES is a map that cyclicly permutes each equivalence class (of characters with the same canonical equivalent). (For ordinary ASCII, this would map `a' into `A' and `A' into `a', and likewise for each set of equivalent characters.) When you construct a case table, you can provide `nil' for CANONICALIZE; then Emacs fills in this slot from the lower case and upper case mappings. You can also provide `nil' for EQUIVALENCES; then Emacs fills in this slot from CANONICALIZE. In a case table that is actually in use, those components are non-`nil'. Do not try to specify EQUIVALENCES without also specifying CANONICALIZE. Here are the functions for working with case tables: - Function: case-table-p OBJECT This predicate returns non-`nil' if OBJECT is a valid case table. - Function: set-standard-case-table TABLE This function makes TABLE the standard case table, so that it will be used in any buffers created subsequently. - Function: standard-case-table This returns the standard case table. - Function: current-case-table This function returns the current buffer's case table. - Function: set-case-table TABLE This sets the current buffer's case table to TABLE. The following three functions are convenient subroutines for packages that define non-ASCII character sets. They modify the specified case table CASE-TABLE; they also modify the standard syntax table. *Note Syntax Tables::. Normally you would use these functions to change the standard case table. - Function: set-case-syntax-pair UC LC CASE-TABLE This function specifies a pair of corresponding letters, one upper case and one lower case. - Function: set-case-syntax-delims L R CASE-TABLE This function makes characters L and R a matching pair of case-invariant delimiters. - Function: set-case-syntax CHAR SYNTAX CASE-TABLE This function makes CHAR case-invariant, with syntax SYNTAX. - Command: describe-buffer-case-table This command displays a description of the contents of the current buffer's case table.  File: elisp, Node: Lists, Next: Sequences Arrays Vectors, Prev: Strings and Characters, Up: Top Lists ***** A "list" represents a sequence of zero or more elements (which may be any Lisp objects). The important difference between lists and vectors is that two or more lists can share part of their structure; in addition, you can insert or delete elements in a list without copying the whole list. * Menu: * Cons Cells:: How lists are made out of cons cells. * Lists as Boxes:: Graphical notation to explain lists. * List-related Predicates:: Is this object a list? Comparing two lists. * List Elements:: Extracting the pieces of a list. * Building Lists:: Creating list structure. * Modifying Lists:: Storing new pieces into an existing list. * Sets And Lists:: A list can represent a finite mathematical set. * Association Lists:: A list can represent a finite relation or mapping.  File: elisp, Node: Cons Cells, Next: Lists as Boxes, Up: Lists Lists and Cons Cells ==================== Lists in Lisp are not a primitive data type; they are built up from "cons cells". A cons cell is a data object that represents an ordered pair. It holds, or "points to," two Lisp objects, one labeled as the CAR, and the other labeled as the CDR. These names are traditional; see *Note Cons Cell Type::. CDR is pronounced "could-er." A list is a series of cons cells chained together, one cons cell per element of the list. By convention, the CARs of the cons cells are the elements of the list, and the CDRs are used to chain the list: the CDR of each cons cell is the following cons cell. The CDR of the last cons cell is `nil'. This asymmetry between the CAR and the CDR is entirely a matter of convention; at the level of cons cells, the CAR and CDR slots have the same characteristics. Because most cons cells are used as part of lists, the phrase "list structure" has come to mean any structure made out of cons cells. The symbol `nil' is considered a list as well as a symbol; it is the list with no elements. For convenience, the symbol `nil' is considered to have `nil' as its CDR (and also as its CAR). The CDR of any nonempty list L is a list containing all the elements of L except the first.  File: elisp, Node: Lists as Boxes, Next: List-related Predicates, Prev: Cons Cells, Up: Lists Lists as Linked Pairs of Boxes ============================== A cons cell can be illustrated as a pair of boxes. The first box represents the CAR and the second box represents the CDR. Here is an illustration of the two-element list, `(tulip lily)', made from two cons cells: --------------- --------------- | car | cdr | | car | cdr | | tulip | o---------->| lily | nil | | | | | | | --------------- --------------- Each pair of boxes represents a cons cell. Each box "refers to", "points to" or "contains" a Lisp object. (These terms are synonymous.) The first box, which describes the CAR of the first cons cell, contains the symbol `tulip'. The arrow from the CDR box of the first cons cell to the second cons cell indicates that the CDR of the first cons cell is the second cons cell. The same list can be illustrated in a different sort of box notation like this: --- --- --- --- | | |--> | | |--> nil --- --- --- --- | | | | --> tulip --> lily Here is a more complex illustration, showing the three-element list, `((pine needles) oak maple)', the first element of which is a two-element list: --- --- --- --- --- --- | | |--> | | |--> | | |--> nil --- --- --- --- --- --- | | | | | | | --> oak --> maple | | --- --- --- --- --> | | |--> | | |--> nil --- --- --- --- | | | | --> pine --> needles The same list represented in the first box notation looks like this: -------------- -------------- -------------- | car | cdr | | car | cdr | | car | cdr | | o | o------->| oak | o------->| maple | nil | | | | | | | | | | | -- | --------- -------------- -------------- | | | -------------- ---------------- | | car | cdr | | car | cdr | ------>| pine | o------->| needles | nil | | | | | | | -------------- ---------------- *Note Cons Cell Type::, for the read and print syntax of cons cells and lists, and for more "box and arrow" illustrations of lists.  File: elisp, Node: List-related Predicates, Next: List Elements, Prev: Lists as Boxes, Up: Lists Predicates on Lists =================== The following predicates test whether a Lisp object is an atom, is a cons cell or is a list, or whether it is the distinguished object `nil'. (Many of these predicates can be defined in terms of the others, but they are used so often that it is worth having all of them.) - Function: consp OBJECT This function returns `t' if OBJECT is a cons cell, `nil' otherwise. `nil' is not a cons cell, although it *is* a list. - Function: atom OBJECT This function returns `t' if OBJECT is an atom, `nil' otherwise. All objects except cons cells are atoms. The symbol `nil' is an atom and is also a list; it is the only Lisp object that is both. (atom OBJECT) == (not (consp OBJECT)) - Function: listp OBJECT This function returns `t' if OBJECT is a cons cell or `nil'. Otherwise, it returns `nil'. (listp '(1)) => t (listp '()) => t - Function: nlistp OBJECT This function is the opposite of `listp': it returns `t' if OBJECT is not a list. Otherwise, it returns `nil'. (listp OBJECT) == (not (nlistp OBJECT)) - Function: null OBJECT This function returns `t' if OBJECT is `nil', and returns `nil' otherwise. This function is identical to `not', but as a matter of clarity we use `null' when OBJECT is considered a list and `not' when it is considered a truth value (see `not' in *Note Combining Conditions::). (null '(1)) => nil (null '()) => t  File: elisp, Node: List Elements, Next: Building Lists, Prev: List-related Predicates, Up: Lists Accessing Elements of Lists =========================== - Function: car CONS-CELL This function returns the value pointed to by the first pointer of the cons cell CONS-CELL. Expressed another way, this function returns the CAR of CONS-CELL. As a special case, if CONS-CELL is `nil', then `car' is defined to return `nil'; therefore, any list is a valid argument for `car'. An error is signaled if the argument is not a cons cell or `nil'. (car '(a b c)) => a (car '()) => nil - Function: cdr CONS-CELL This function returns the value pointed to by the second pointer of the cons cell CONS-CELL. Expressed another way, this function returns the CDR of CONS-CELL. As a special case, if CONS-CELL is `nil', then `cdr' is defined to return `nil'; therefore, any list is a valid argument for `cdr'. An error is signaled if the argument is not a cons cell or `nil'. (cdr '(a b c)) => (b c) (cdr '()) => nil - Function: car-safe OBJECT This function lets you take the CAR of a cons cell while avoiding errors for other data types. It returns the CAR of OBJECT if OBJECT is a cons cell, `nil' otherwise. This is in contrast to `car', which signals an error if OBJECT is not a list. (car-safe OBJECT) == (let ((x OBJECT)) (if (consp x) (car x) nil)) - Function: cdr-safe OBJECT This function lets you take the CDR of a cons cell while avoiding errors for other data types. It returns the CDR of OBJECT if OBJECT is a cons cell, `nil' otherwise. This is in contrast to `cdr', which signals an error if OBJECT is not a list. (cdr-safe OBJECT) == (let ((x OBJECT)) (if (consp x) (cdr x) nil)) - Function: nth N LIST This function returns the Nth element of LIST. Elements are numbered starting with zero, so the CAR of LIST is element number zero. If the length of LIST is N or less, the value is `nil'. If N is negative, `nth' returns the first element of LIST. (nth 2 '(1 2 3 4)) => 3 (nth 10 '(1 2 3 4)) => nil (nth -3 '(1 2 3 4)) => 1 (nth n x) == (car (nthcdr n x)) The function `elt' is similar, but applies to any kind of sequence. For historical reasons, it takes its arguments in the opposite order. *Note Sequence Functions::. - Function: nthcdr N LIST This function returns the Nth CDR of LIST. In other words, it skips past the first N links of LIST and returns what follows. If N is zero or negative, `nthcdr' returns all of LIST. If the length of LIST is N or less, `nthcdr' returns `nil'. (nthcdr 1 '(1 2 3 4)) => (2 3 4) (nthcdr 10 '(1 2 3 4)) => nil (nthcdr -3 '(1 2 3 4)) => (1 2 3 4) - Function: safe-length LIST This function returns the length of LIST, with no risk of either an error or an infinite loop. If LIST is not really a list, `safe-length' returns 0. If LIST is circular, it returns a finite value which is at least the number of distinct elements. The most common way to compute the length of a list, when you are not worried that it may be circular, is with `length'. *Note Sequence Functions::. - Function: caar CONS-CELL This is the same as `(car (car CONS-CELL))'. - Function: cadr CONS-CELL This is the same as `(car (cdr CONS-CELL))' or `(nth 1 CONS-CELL)'. - Function: cdar CONS-CELL This is the same as `(cdr (car CONS-CELL))'. - Function: cddr CONS-CELL This is the same as `(cdr (cdr CONS-CELL))' or `(nthcdr 2 CONS-CELL)'.  File: elisp, Node: Building Lists, Next: Modifying Lists, Prev: List Elements, Up: Lists Building Cons Cells and Lists ============================= Many functions build lists, as lists reside at the very heart of Lisp. `cons' is the fundamental list-building function; however, it is interesting to note that `list' is used more times in the source code for Emacs than `cons'. - Function: cons OBJECT1 OBJECT2 This function is the fundamental function used to build new list structure. It creates a new cons cell, making OBJECT1 the CAR, and OBJECT2 the CDR. It then returns the new cons cell. The arguments OBJECT1 and OBJECT2 may be any Lisp objects, but most often OBJECT2 is a list. (cons 1 '(2)) => (1 2) (cons 1 '()) => (1) (cons 1 2) => (1 . 2) `cons' is often used to add a single element to the front of a list. This is called "consing the element onto the list". For example: (setq list (cons newelt list)) Note that there is no conflict between the variable named `list' used in this example and the function named `list' described below; any symbol can serve both purposes. - Function: list &rest OBJECTS This function creates a list with OBJECTS as its elements. The resulting list is always `nil'-terminated. If no OBJECTS are given, the empty list is returned. (list 1 2 3 4 5) => (1 2 3 4 5) (list 1 2 '(3 4 5) 'foo) => (1 2 (3 4 5) foo) (list) => nil - Function: make-list LENGTH OBJECT This function creates a list of length LENGTH, in which all the elements have the identical value OBJECT. Compare `make-list' with `make-string' (*note Creating Strings::.). (make-list 3 'pigs) => (pigs pigs pigs) (make-list 0 'pigs) => nil - Function: append &rest SEQUENCES This function returns a list containing all the elements of SEQUENCES. The SEQUENCES may be lists, vectors, bool-vectors, or strings, but the last one should usually be a list. All arguments except the last one are copied, so none of the arguments is altered. (See `nconc' in *Note Rearrangement::, for a way to join lists with no copying.) More generally, the final argument to `append' may be any Lisp object. The final argument is not copied or converted; it becomes the CDR of the last cons cell in the new list. If the final argument is itself a list, then its elements become in effect elements of the result list. If the final element is not a list, the result is a "dotted list" since its final CDR is not `nil' as required in a true list. The `append' function also allows integers as arguments. It converts them to strings of digits, making up the decimal print representation of the integer, and then uses the strings instead of the original integers. *Don't use this feature; we plan to eliminate it. If you already use this feature, change your programs now!* The proper way to convert an integer to a decimal number in this way is with `format' (*note Formatting Strings::.) or `number-to-string' (*note String Conversion::.). Here is an example of using `append': (setq trees '(pine oak)) => (pine oak) (setq more-trees (append '(maple birch) trees)) => (maple birch pine oak) trees => (pine oak) more-trees => (maple birch pine oak) (eq trees (cdr (cdr more-trees))) => t You can see how `append' works by looking at a box diagram. The variable `trees' is set to the list `(pine oak)' and then the variable `more-trees' is set to the list `(maple birch pine oak)'. However, the variable `trees' continues to refer to the original list: more-trees trees | | | --- --- --- --- -> --- --- --- --- --> | | |--> | | |--> | | |--> | | |--> nil --- --- --- --- --- --- --- --- | | | | | | | | --> maple -->birch --> pine --> oak An empty sequence contributes nothing to the value returned by `append'. As a consequence of this, a final `nil' argument forces a copy of the previous argument: trees => (pine oak) (setq wood (append trees nil)) => (pine oak) wood => (pine oak) (eq wood trees) => nil This once was the usual way to copy a list, before the function `copy-sequence' was invented. *Note Sequences Arrays Vectors::. Here we show the use of vectors and strings as arguments to `append': (append [a b] "cd" nil) => (a b 99 100) With the help of `apply' (*note Calling Functions::.), we can append all the lists in a list of lists: (apply 'append '((a b c) nil (x y z) nil)) => (a b c x y z) If no SEQUENCES are given, `nil' is returned: (append) => nil Here are some examples where the final argument is not a list: (append '(x y) 'z) => (x y . z) (append '(x y) [z]) => (x y . [z]) The second example shows that when the final argument is a sequence but not a list, the sequence's elements do not become elements of the resulting list. Instead, the sequence becomes the final CDR, like any other non-list final argument. - Function: reverse LIST This function creates a new list whose elements are the elements of LIST, but in reverse order. The original argument LIST is *not* altered. (setq x '(1 2 3 4)) => (1 2 3 4) (reverse x) => (4 3 2 1) x => (1 2 3 4)  File: elisp, Node: Modifying Lists, Next: Sets And Lists, Prev: Building Lists, Up: Lists Modifying Existing List Structure ================================= You can modify the CAR and CDR contents of a cons cell with the primitives `setcar' and `setcdr'. We call these "destructive" operations because they change existing list structure. Common Lisp note: Common Lisp uses functions `rplaca' and `rplacd' to alter list structure; they change structure the same way as `setcar' and `setcdr', but the Common Lisp functions return the cons cell while `setcar' and `setcdr' return the new CAR or CDR. * Menu: * Setcar:: Replacing an element in a list. * Setcdr:: Replacing part of the list backbone. This can be used to remove or add elements. * Rearrangement:: Reordering the elements in a list; combining lists.  File: elisp, Node: Setcar, Next: Setcdr, Up: Modifying Lists Altering List Elements with `setcar' ------------------------------------ Changing the CAR of a cons cell is done with `setcar'. When used on a list, `setcar' replaces one element of a list with a different element. - Function: setcar CONS OBJECT This function stores OBJECT as the new CAR of CONS, replacing its previous CAR. In other words, it changes the CAR slot of CONS to point to OBJECT. It returns the value OBJECT. For example: (setq x '(1 2)) => (1 2) (setcar x 4) => 4 x => (4 2) When a cons cell is part of the shared structure of several lists, storing a new CAR into the cons changes one element of each of these lists. Here is an example: ;; Create two lists that are partly shared. (setq x1 '(a b c)) => (a b c) (setq x2 (cons 'z (cdr x1))) => (z b c) ;; Replace the CAR of a shared link. (setcar (cdr x1) 'foo) => foo x1 ; Both lists are changed. => (a foo c) x2 => (z foo c) ;; Replace the CAR of a link that is not shared. (setcar x1 'baz) => baz x1 ; Only one list is changed. => (baz foo c) x2 => (z foo c) Here is a graphical depiction of the shared structure of the two lists in the variables `x1' and `x2', showing why replacing `b' changes them both: --- --- --- --- --- --- x1---> | | |----> | | |--> | | |--> nil --- --- --- --- --- --- | --> | | | | | | --> a | --> b --> c | --- --- | x2--> | | |-- --- --- | | --> z Here is an alternative form of box diagram, showing the same relationship: x1: -------------- -------------- -------------- | car | cdr | | car | cdr | | car | cdr | | a | o------->| b | o------->| c | nil | | | | -->| | | | | | -------------- | -------------- -------------- | x2: | -------------- | | car | cdr | | | z | o---- | | | --------------