annotate lispref/lists.texi @ 64495:524cffc1c27d

(describe-char): Create link buttons for `charset' and `code point'. Add the current input method name with a link button to `to input' field. Print face names of display table characters in `The display table entry is displayed by' section instead of printing face-id in the `display' field. Guess hardcoded faces and create a link button for them. Skip empty fields when calculating max-width. Treat `widget-create' specially while inserting strings from the collected field list. (describe-char-after): Made obsolete in version 22.1, not 21.5.
author Juri Linkov <juri@jurta.org>
date Tue, 19 Jul 2005 11:23:14 +0000
parents d667a89621c9
children e836425ee789 b7da78284d4c
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
56215
c9aa4127a482 Reposition @anchor's.
Luc Teirlinck <teirllm@auburn.edu>
parents: 55735
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
60053
ce7d7b779c21 (Lists): Remove reference to deleted node.
Lute Kamstra <lute@gnu.org>
parents: 60040
diff changeset
4 @c 2003, 2004, 2005
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39200
diff changeset
5 @c Free Software Foundation, Inc.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @c See the file elisp.texi for copying conditions.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
7 @setfilename ../info/lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @node Lists, Sequences Arrays Vectors, Strings and Characters, Top
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9 @chapter Lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10 @cindex list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11 @cindex element (of list)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13 A @dfn{list} represents a sequence of zero or more elements (which may
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 be any Lisp objects). The important difference between lists and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15 vectors is that two or more lists can share part of their structure; in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16 addition, you can insert or delete elements in a list without copying
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17 the whole list.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
19 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 * Cons Cells:: How lists are made out of cons cells.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21 * List-related Predicates:: Is this object a list? Comparing two lists.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
22 * List Elements:: Extracting the pieces of a list.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23 * Building Lists:: Creating list structure.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
24 * Modifying Lists:: Storing new pieces into an existing list.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
25 * Sets And Lists:: A list can represent a finite mathematical set.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26 * Association Lists:: A list can represent a finite relation or mapping.
63541
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
27 * Rings:: Managing a fixed-size ring of objects.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30 @node Cons Cells
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 @section Lists and Cons Cells
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 @cindex lists and cons cells
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33 @cindex @code{nil} and lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35 Lists in Lisp are not a primitive data type; they are built up from
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
36 @dfn{cons cells}. A cons cell is a data object that represents an
27068
d00d63002726 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25751
diff changeset
37 ordered pair. That is, it has two slots, and each slot @dfn{holds}, or
d00d63002726 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25751
diff changeset
38 @dfn{refers to}, some Lisp object. One slot is known as the @sc{car},
d00d63002726 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25751
diff changeset
39 and the other is known as the @sc{cdr}. (These names are traditional;
d00d63002726 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25751
diff changeset
40 see @ref{Cons Cell Type}.) @sc{cdr} is pronounced ``could-er.''
d00d63002726 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25751
diff changeset
41
d00d63002726 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25751
diff changeset
42 We say that ``the @sc{car} of this cons cell is'' whatever object
d00d63002726 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25751
diff changeset
43 its @sc{car} slot currently holds, and likewise for the @sc{cdr}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
44
27068
d00d63002726 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25751
diff changeset
45 A list is a series of cons cells ``chained together,'' so that each
27332
5cfe77eaff45 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27193
diff changeset
46 cell refers to the next one. There is one cons cell for each element of
27068
d00d63002726 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25751
diff changeset
47 the list. By convention, the @sc{car}s of the cons cells hold the
d00d63002726 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25751
diff changeset
48 elements of the list, and the @sc{cdr}s are used to chain the list: the
d00d63002726 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25751
diff changeset
49 @sc{cdr} slot of each cons cell refers to the following cons cell. The
d00d63002726 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25751
diff changeset
50 @sc{cdr} of the last cons cell is @code{nil}. This asymmetry between
d00d63002726 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25751
diff changeset
51 the @sc{car} and the @sc{cdr} is entirely a matter of convention; at the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52 level of cons cells, the @sc{car} and @sc{cdr} slots have the same
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53 characteristics.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
54
55735
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
55 @cindex true list
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
56 Since @code{nil} is the conventional value to put in the @sc{cdr} of
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
57 the last cons cell in the list, we call that case a @dfn{true list}.
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
58
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
59 In Lisp, we consider the symbol @code{nil} a list as well as a
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
60 symbol; it is the list with no elements. For convenience, the symbol
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
61 @code{nil} is considered to have @code{nil} as its @sc{cdr} (and also
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
62 as its @sc{car}). Therefore, the @sc{cdr} of a true list is always a
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
63 true list.
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
64
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
65 @cindex dotted list
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
66 @cindex circular list
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
67 If the @sc{cdr} of a list's last cons cell is some other value,
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
68 neither @code{nil} nor another cons cell, we call the structure a
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
69 @dfn{dotted list}, since its printed representation would use
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
70 @samp{.}. There is one other possibility: some cons cell's @sc{cdr}
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
71 could point to one of the previous cons cells in the list. We call
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
72 that structure a @dfn{circular list}.
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
73
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
74 For some purposes, it does not matter whether a list is true,
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
75 circular or dotted. If the program doesn't look far enough down the
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
76 list to see the @sc{cdr} of the final cons cell, it won't care.
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
77 However, some functions that operate on lists demand true lists and
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
78 signal errors if given a dotted list. Most functions that try to find
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
79 the end of a list enter infinite loops if given a circular list.
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
80
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
81 @cindex list structure
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
82 Because most cons cells are used as part of lists, the phrase
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
83 @dfn{list structure} has come to mean any structure made out of cons
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
84 cells.
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
85
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86 The @sc{cdr} of any nonempty list @var{l} is a list containing all the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87 elements of @var{l} except the first.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
89 @xref{Cons Cell Type}, for the read and print syntax of cons cells and
60053
ce7d7b779c21 (Lists): Remove reference to deleted node.
Lute Kamstra <lute@gnu.org>
parents: 60040
diff changeset
90 lists, and for ``box and arrow'' illustrations of lists.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
92 @node List-related Predicates
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93 @section Predicates on Lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
94
60040
24dd4b5475b4 (List-related Predicates): Minor wording improvement.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
95 The following predicates test whether a Lisp object is an atom,
24dd4b5475b4 (List-related Predicates): Minor wording improvement.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
96 whether it is a cons cell or is a list, or whether it is the
24dd4b5475b4 (List-related Predicates): Minor wording improvement.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
97 distinguished object @code{nil}. (Many of these predicates can be
24dd4b5475b4 (List-related Predicates): Minor wording improvement.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
98 defined in terms of the others, but they are used so often that it is
24dd4b5475b4 (List-related Predicates): Minor wording improvement.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
99 worth having all of them.)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
101 @defun consp object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102 This function returns @code{t} if @var{object} is a cons cell, @code{nil}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 otherwise. @code{nil} is not a cons cell, although it @emph{is} a list.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106 @defun atom object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
107 @cindex atoms
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
108 This function returns @code{t} if @var{object} is an atom, @code{nil}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
109 otherwise. All objects except cons cells are atoms. The symbol
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110 @code{nil} is an atom and is also a list; it is the only Lisp object
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
111 that is both.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
113 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114 (atom @var{object}) @equiv{} (not (consp @var{object}))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
116 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118 @defun listp object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119 This function returns @code{t} if @var{object} is a cons cell or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 @code{nil}. Otherwise, it returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
121
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124 (listp '(1))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125 @result{} t
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
127 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128 (listp '())
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129 @result{} t
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 @defun nlistp object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135 This function is the opposite of @code{listp}: it returns @code{t} if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136 @var{object} is not a list. Otherwise, it returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
138 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139 (listp @var{object}) @equiv{} (not (nlistp @var{object}))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143 @defun null object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144 This function returns @code{t} if @var{object} is @code{nil}, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145 returns @code{nil} otherwise. This function is identical to @code{not},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146 but as a matter of clarity we use @code{null} when @var{object} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147 considered a list and @code{not} when it is considered a truth value
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148 (see @code{not} in @ref{Combining Conditions}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152 (null '(1))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156 (null '())
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157 @result{} t
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
159 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161
7734
2d4db32cccd5 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7337
diff changeset
162 @need 2000
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164 @node List Elements
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
165 @section Accessing Elements of Lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
166 @cindex list elements
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
168 @defun car cons-cell
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22961
diff changeset
169 This function returns the value referred to by the first slot of the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170 cons cell @var{cons-cell}. Expressed another way, this function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171 returns the @sc{car} of @var{cons-cell}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
172
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173 As a special case, if @var{cons-cell} is @code{nil}, then @code{car}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174 is defined to return @code{nil}; therefore, any list is a valid argument
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175 for @code{car}. An error is signaled if the argument is not a cons cell
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176 or @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
177
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180 (car '(a b c))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181 @result{} a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
183 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184 (car '())
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
185 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
187 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
189
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
190 @defun cdr cons-cell
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22961
diff changeset
191 This function returns the value referred to by the second slot of
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192 the cons cell @var{cons-cell}. Expressed another way, this function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193 returns the @sc{cdr} of @var{cons-cell}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
194
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
195 As a special case, if @var{cons-cell} is @code{nil}, then @code{cdr}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
196 is defined to return @code{nil}; therefore, any list is a valid argument
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
197 for @code{cdr}. An error is signaled if the argument is not a cons cell
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
198 or @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
199
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
200 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
201 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202 (cdr '(a b c))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
203 @result{} (b c)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
204 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
206 (cdr '())
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
207 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
208 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
211
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
212 @defun car-safe object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213 This function lets you take the @sc{car} of a cons cell while avoiding
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214 errors for other data types. It returns the @sc{car} of @var{object} if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215 @var{object} is a cons cell, @code{nil} otherwise. This is in contrast
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216 to @code{car}, which signals an error if @var{object} is not a list.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
217
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220 (car-safe @var{object})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221 @equiv{}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222 (let ((x @var{object}))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 (if (consp x)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224 (car x)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225 nil))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 @defun cdr-safe object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231 This function lets you take the @sc{cdr} of a cons cell while
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232 avoiding errors for other data types. It returns the @sc{cdr} of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
233 @var{object} if @var{object} is a cons cell, @code{nil} otherwise.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
234 This is in contrast to @code{cdr}, which signals an error if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
235 @var{object} is not a list.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
236
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
238 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239 (cdr-safe @var{object})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240 @equiv{}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241 (let ((x @var{object}))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242 (if (consp x)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243 (cdr x)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244 nil))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
249 @tindex pop
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
250 @defmac pop listname
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
251 This macro is a way of examining the @sc{car} of a list,
60448
1f2f39d6b2e7 (List Elements, Building Lists): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents: 60053
diff changeset
252 and taking it off the list, all at once.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
253
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
254 It operates on the list which is stored in the symbol @var{listname}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
255 It removes this element from the list by setting @var{listname}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
256 to the @sc{cdr} of its old value---but it also returns the @sc{car}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
257 of that list, which is the element being removed.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
258
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
259 @example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
260 x
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
261 @result{} (a b c)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
262 (pop x)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
263 @result{} a
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
264 x
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
265 @result{} (b c)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
266 @end example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
267 @end defmac
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
268
56215
c9aa4127a482 Reposition @anchor's.
Luc Teirlinck <teirllm@auburn.edu>
parents: 55735
diff changeset
269 @defun nth n list
54945
70fd47f8342a Add anchors. Some other minor changes.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54264
diff changeset
270 @anchor{Definition of nth}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 This function returns the @var{n}th element of @var{list}. Elements
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 are numbered starting with zero, so the @sc{car} of @var{list} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273 element number zero. If the length of @var{list} is @var{n} or less,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274 the value is @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276 If @var{n} is negative, @code{nth} returns the first element of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277 @var{list}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281 (nth 2 '(1 2 3 4))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282 @result{} 3
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285 (nth 10 '(1 2 3 4))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289 (nth -3 '(1 2 3 4))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
290 @result{} 1
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292 (nth n x) @equiv{} (car (nthcdr n x))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294 @end example
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
295
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
296 The function @code{elt} is similar, but applies to any kind of sequence.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
297 For historical reasons, it takes its arguments in the opposite order.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
298 @xref{Sequence Functions}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
301 @defun nthcdr n list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
302 This function returns the @var{n}th @sc{cdr} of @var{list}. In other
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13229
diff changeset
303 words, it skips past the first @var{n} links of @var{list} and returns
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304 what follows.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306 If @var{n} is zero or negative, @code{nthcdr} returns all of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307 @var{list}. If the length of @var{list} is @var{n} or less,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
308 @code{nthcdr} returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
312 (nthcdr 1 '(1 2 3 4))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313 @result{} (2 3 4)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316 (nthcdr 10 '(1 2 3 4))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320 (nthcdr -3 '(1 2 3 4))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321 @result{} (1 2 3 4)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325
31131
fe7ff8fb99dc Add `last'.
Dave Love <fx@gnu.org>
parents: 30808
diff changeset
326 @defun last list &optional n
51703
b8860fc285cb Minor Texinfo usage fix.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
327 This function returns the last link of @var{list}. The @code{car} of
b8860fc285cb Minor Texinfo usage fix.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
328 this link is the list's last element. If @var{list} is null,
b8860fc285cb Minor Texinfo usage fix.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
329 @code{nil} is returned. If @var{n} is non-@code{nil}, the
b8860fc285cb Minor Texinfo usage fix.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
330 @var{n}th-to-last link is returned instead, or the whole of @var{list}
b8860fc285cb Minor Texinfo usage fix.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
331 if @var{n} is bigger than @var{list}'s length.
31131
fe7ff8fb99dc Add `last'.
Dave Love <fx@gnu.org>
parents: 30808
diff changeset
332 @end defun
fe7ff8fb99dc Add `last'.
Dave Love <fx@gnu.org>
parents: 30808
diff changeset
333
56215
c9aa4127a482 Reposition @anchor's.
Luc Teirlinck <teirllm@auburn.edu>
parents: 55735
diff changeset
334 @defun safe-length list
54945
70fd47f8342a Add anchors. Some other minor changes.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54264
diff changeset
335 @anchor{Definition of safe-length}
55735
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
336 This function returns the length of @var{list}, with no risk of either
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
337 an error or an infinite loop. It generally returns the number of
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
338 distinct cons cells in the list. However, for circular lists,
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
339 the value is just an upper bound; it is often too large.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13229
diff changeset
340
55735
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
341 If @var{list} is not @code{nil} or a cons cell, @code{safe-length}
1874eee23678 (Cons Cells): Explain dotted lists, true lists, circular lists.
Richard M. Stallman <rms@gnu.org>
parents: 54945
diff changeset
342 returns 0.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13229
diff changeset
343 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13229
diff changeset
344
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
345 The most common way to compute the length of a list, when you are not
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
346 worried that it may be circular, is with @code{length}. @xref{Sequence
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
347 Functions}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
348
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
349 @defun caar cons-cell
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
350 This is the same as @code{(car (car @var{cons-cell}))}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13229
diff changeset
351 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13229
diff changeset
352
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
353 @defun cadr cons-cell
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
354 This is the same as @code{(car (cdr @var{cons-cell}))}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
355 or @code{(nth 1 @var{cons-cell})}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13229
diff changeset
356 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13229
diff changeset
357
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
358 @defun cdar cons-cell
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
359 This is the same as @code{(cdr (car @var{cons-cell}))}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13229
diff changeset
360 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13229
diff changeset
361
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
362 @defun cddr cons-cell
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
363 This is the same as @code{(cdr (cdr @var{cons-cell}))}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
364 or @code{(nthcdr 2 @var{cons-cell})}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13229
diff changeset
365 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13229
diff changeset
366
35090
b876bd6bde9e butlast, nbutlast.
Dave Love <fx@gnu.org>
parents: 33428
diff changeset
367 @defun butlast x &optional n
b876bd6bde9e butlast, nbutlast.
Dave Love <fx@gnu.org>
parents: 33428
diff changeset
368 This function returns the list @var{x} with the last element,
b876bd6bde9e butlast, nbutlast.
Dave Love <fx@gnu.org>
parents: 33428
diff changeset
369 or the last @var{n} elements, removed. If @var{n} is greater
b876bd6bde9e butlast, nbutlast.
Dave Love <fx@gnu.org>
parents: 33428
diff changeset
370 than zero it makes a copy of the list so as not to damage the
b876bd6bde9e butlast, nbutlast.
Dave Love <fx@gnu.org>
parents: 33428
diff changeset
371 original list. In general, @code{(append (butlast @var{x} @var{n})
b876bd6bde9e butlast, nbutlast.
Dave Love <fx@gnu.org>
parents: 33428
diff changeset
372 (last @var{x} @var{n}))} will return a list equal to @var{x}.
b876bd6bde9e butlast, nbutlast.
Dave Love <fx@gnu.org>
parents: 33428
diff changeset
373 @end defun
b876bd6bde9e butlast, nbutlast.
Dave Love <fx@gnu.org>
parents: 33428
diff changeset
374
b876bd6bde9e butlast, nbutlast.
Dave Love <fx@gnu.org>
parents: 33428
diff changeset
375 @defun nbutlast x &optional n
b876bd6bde9e butlast, nbutlast.
Dave Love <fx@gnu.org>
parents: 33428
diff changeset
376 This is a version of @code{butlast} that works by destructively
b876bd6bde9e butlast, nbutlast.
Dave Love <fx@gnu.org>
parents: 33428
diff changeset
377 modifying the @code{cdr} of the appropriate element, rather than
b876bd6bde9e butlast, nbutlast.
Dave Love <fx@gnu.org>
parents: 33428
diff changeset
378 making a copy of the list.
b876bd6bde9e butlast, nbutlast.
Dave Love <fx@gnu.org>
parents: 33428
diff changeset
379 @end defun
b876bd6bde9e butlast, nbutlast.
Dave Love <fx@gnu.org>
parents: 33428
diff changeset
380
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381 @node Building Lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
383 @section Building Cons Cells and Lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
384 @cindex cons cells
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
385 @cindex building lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
386
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387 Many functions build lists, as lists reside at the very heart of Lisp.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
388 @code{cons} is the fundamental list-building function; however, it is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389 interesting to note that @code{list} is used more times in the source
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390 code for Emacs than @code{cons}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392 @defun cons object1 object2
54264
9fd3a94524eb (Building Lists): Minor clarification.
Richard M. Stallman <rms@gnu.org>
parents: 54047
diff changeset
393 This function is the most basic function for building new list
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
394 structure. It creates a new cons cell, making @var{object1} the
54264
9fd3a94524eb (Building Lists): Minor clarification.
Richard M. Stallman <rms@gnu.org>
parents: 54047
diff changeset
395 @sc{car}, and @var{object2} the @sc{cdr}. It then returns the new
9fd3a94524eb (Building Lists): Minor clarification.
Richard M. Stallman <rms@gnu.org>
parents: 54047
diff changeset
396 cons cell. The arguments @var{object1} and @var{object2} may be any
9fd3a94524eb (Building Lists): Minor clarification.
Richard M. Stallman <rms@gnu.org>
parents: 54047
diff changeset
397 Lisp objects, but most often @var{object2} is a list.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401 (cons 1 '(2))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402 @result{} (1 2)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
404 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405 (cons 1 '())
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406 @result{} (1)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
407 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
408 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409 (cons 1 2)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
410 @result{} (1 . 2)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414 @cindex consing
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 @code{cons} is often used to add a single element to the front of a
33428
ca84a4992948 (Building Lists): Add footnote to explain how to add
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 31131
diff changeset
416 list. This is called @dfn{consing the element onto the list}.
ca84a4992948 (Building Lists): Add footnote to explain how to add
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 31131
diff changeset
417 @footnote{There is no strictly equivalent way to add an element to
ca84a4992948 (Building Lists): Add footnote to explain how to add
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 31131
diff changeset
418 the end of a list. You can use @code{(append @var{listname} (list
ca84a4992948 (Building Lists): Add footnote to explain how to add
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 31131
diff changeset
419 @var{newelt}))}, which creates a whole new list by copying @var{listname}
ca84a4992948 (Building Lists): Add footnote to explain how to add
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 31131
diff changeset
420 and adding @var{newelt} to its end. Or you can use @code{(nconc
ca84a4992948 (Building Lists): Add footnote to explain how to add
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 31131
diff changeset
421 @var{listname} (list @var{newelt}))}, which modifies @var{listname}
ca84a4992948 (Building Lists): Add footnote to explain how to add
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 31131
diff changeset
422 by following all the @sc{cdr}s and then replacing the terminating
ca84a4992948 (Building Lists): Add footnote to explain how to add
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 31131
diff changeset
423 @code{nil}. Compare this to adding an element to the beginning of a
ca84a4992948 (Building Lists): Add footnote to explain how to add
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 31131
diff changeset
424 list with @code{cons}, which neither copies nor modifies the list.}
ca84a4992948 (Building Lists): Add footnote to explain how to add
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 31131
diff changeset
425 For example:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428 (setq list (cons newelt list))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
430
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431 Note that there is no conflict between the variable named @code{list}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432 used in this example and the function named @code{list} described below;
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
433 any symbol can serve both purposes.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
434 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
435
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
436 @tindex push
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
437 @defmac push newelt listname
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
438 This macro provides an alternative way to write
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
439 @code{(setq @var{listname} (cons @var{newelt} @var{listname}))}.
38786
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
440
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
441 @example
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39200
diff changeset
442 (setq l '(a b))
38786
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
443 @result{} (a b)
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
444 (push 'c l)
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
445 @result{} (c a b)
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
446 l
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
447 @result{} (c a b)
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
448 @end example
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
449 @end defmac
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
450
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 @defun list &rest objects
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452 This function creates a list with @var{objects} as its elements. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453 resulting list is always @code{nil}-terminated. If no @var{objects}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454 are given, the empty list is returned.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 (list 1 2 3 4 5)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 @result{} (1 2 3 4 5)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462 (list 1 2 '(3 4 5) 'foo)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463 @result{} (1 2 (3 4 5) foo)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 (list)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472 @defun make-list length object
38786
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
473 This function creates a list of @var{length} elements, in which each
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
474 element is @var{object}. Compare @code{make-list} with
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
475 @code{make-string} (@pxref{Creating Strings}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479 (make-list 3 'pigs)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480 @result{} (pigs pigs pigs)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
482 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483 (make-list 0 'pigs)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
485 @end group
38786
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
486 @group
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
487 (setq l (make-list 3 '(a b))
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
488 @result{} ((a b) (a b) (a b))
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
489 (eq (car l) (cadr l))
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
490 @result{} t
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
491 @end group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
492 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
493 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
494
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
495 @defun append &rest sequences
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
496 @cindex copying lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
497 This function returns a list containing all the elements of
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
498 @var{sequences}. The @var{sequences} may be lists, vectors,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
499 bool-vectors, or strings, but the last one should usually be a list.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
500 All arguments except the last one are copied, so none of the arguments
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
501 is altered. (See @code{nconc} in @ref{Rearrangement}, for a way to join
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
502 lists with no copying.)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
503
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
504 More generally, the final argument to @code{append} may be any Lisp
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
505 object. The final argument is not copied or converted; it becomes the
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
506 @sc{cdr} of the last cons cell in the new list. If the final argument
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
507 is itself a list, then its elements become in effect elements of the
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
508 result list. If the final element is not a list, the result is a
54945
70fd47f8342a Add anchors. Some other minor changes.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54264
diff changeset
509 dotted list since its final @sc{cdr} is not @code{nil} as required
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
510 in a true list.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
511
53194
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
512 In Emacs 20 and before, the @code{append} function also allowed
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
513 integers as (non last) arguments. It converted them to strings of
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
514 digits, making up the decimal print representation of the integer, and
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
515 then used the strings instead of the original integers. This obsolete
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
516 usage no longer works. The proper way to convert an integer to a
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
517 decimal number in this way is with @code{format} (@pxref{Formatting
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
518 Strings}) or @code{number-to-string} (@pxref{String Conversion}).
22274
f0cd03a7dac9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
519 @end defun
f0cd03a7dac9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
520
f0cd03a7dac9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
521 Here is an example of using @code{append}:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
523 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525 (setq trees '(pine oak))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 @result{} (pine oak)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527 (setq more-trees (append '(maple birch) trees))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
528 @result{} (maple birch pine oak)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
529 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
530
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
531 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
532 trees
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
533 @result{} (pine oak)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
534 more-trees
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
535 @result{} (maple birch pine oak)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
536 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
537 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538 (eq trees (cdr (cdr more-trees)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 @result{} t
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
541 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542
22274
f0cd03a7dac9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
543 You can see how @code{append} works by looking at a box diagram. The
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
544 variable @code{trees} is set to the list @code{(pine oak)} and then the
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
545 variable @code{more-trees} is set to the list @code{(maple birch pine
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
546 oak)}. However, the variable @code{trees} continues to refer to the
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
547 original list:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551 more-trees trees
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
552 | |
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
553 | --- --- --- --- -> --- --- --- ---
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
554 --> | | |--> | | |--> | | |--> | | |--> nil
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
555 --- --- --- --- --- --- --- ---
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556 | | | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
557 | | | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
558 --> maple -->birch --> pine --> oak
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
559 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
560 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561
22274
f0cd03a7dac9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
562 An empty sequence contributes nothing to the value returned by
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563 @code{append}. As a consequence of this, a final @code{nil} argument
22274
f0cd03a7dac9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
564 forces a copy of the previous argument:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
565
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
567 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
568 trees
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
569 @result{} (pine oak)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
570 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
571 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
572 (setq wood (append trees nil))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573 @result{} (pine oak)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
574 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
575 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
576 wood
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577 @result{} (pine oak)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
578 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
579 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580 (eq wood trees)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
583 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
584
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586 This once was the usual way to copy a list, before the function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
587 @code{copy-sequence} was invented. @xref{Sequences Arrays Vectors}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
588
22274
f0cd03a7dac9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
589 Here we show the use of vectors and strings as arguments to @code{append}:
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
590
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
591 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
592 @group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
593 (append [a b] "cd" nil)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
594 @result{} (a b 99 100)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
595 @end group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
596 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
597
22274
f0cd03a7dac9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
598 With the help of @code{apply} (@pxref{Calling Functions}), we can append
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
599 all the lists in a list of lists:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
600
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
601 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
602 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
603 (apply 'append '((a b c) nil (x y z) nil))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
604 @result{} (a b c x y z)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
605 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
606 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
607
22274
f0cd03a7dac9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
608 If no @var{sequences} are given, @code{nil} is returned:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
609
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
610 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
611 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
612 (append)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
614 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
615 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
616
22274
f0cd03a7dac9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
617 Here are some examples where the final argument is not a list:
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
618
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
619 @example
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
620 (append '(x y) 'z)
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
621 @result{} (x y . z)
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
622 (append '(x y) [z])
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
623 @result{} (x y . [z])
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
624 @end example
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
625
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
626 @noindent
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
627 The second example shows that when the final argument is a sequence but
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
628 not a list, the sequence's elements do not become elements of the
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
629 resulting list. Instead, the sequence becomes the final @sc{cdr}, like
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
630 any other non-list final argument.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
631
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
632 @defun reverse list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
633 This function creates a new list whose elements are the elements of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 @var{list}, but in reverse order. The original argument @var{list} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
635 @emph{not} altered.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
636
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
637 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
638 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
639 (setq x '(1 2 3 4))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
640 @result{} (1 2 3 4)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
641 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
642 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
643 (reverse x)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
644 @result{} (4 3 2 1)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645 x
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
646 @result{} (1 2 3 4)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
647 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
648 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
649 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650
52484
c2a16cb1821e (Building Lists): Add copy-tree.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
651 @defun copy-tree tree &optional vecp
54945
70fd47f8342a Add anchors. Some other minor changes.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54264
diff changeset
652 This function returns a copy of the tree @code{tree}. If @var{tree} is a
52484
c2a16cb1821e (Building Lists): Add copy-tree.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
653 cons cell, this makes a new cons cell with the same @sc{car} and
c2a16cb1821e (Building Lists): Add copy-tree.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
654 @sc{cdr}, then recursively copies the @sc{car} and @sc{cdr} in the
c2a16cb1821e (Building Lists): Add copy-tree.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
655 same way.
c2a16cb1821e (Building Lists): Add copy-tree.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
656
c2a16cb1821e (Building Lists): Add copy-tree.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
657 Normally, when @var{tree} is anything other than a cons cell,
c2a16cb1821e (Building Lists): Add copy-tree.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
658 @code{copy-tree} simply returns @var{tree}. However, if @var{vecp} is
c2a16cb1821e (Building Lists): Add copy-tree.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
659 non-@code{nil}, it copies vectors too (and operates recursively on
c2a16cb1821e (Building Lists): Add copy-tree.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
660 their elements).
c2a16cb1821e (Building Lists): Add copy-tree.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
661 @end defun
c2a16cb1821e (Building Lists): Add copy-tree.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
662
53194
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
663 @defun number-sequence from &optional to separation
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
664 This returns a list of numbers starting with @var{from} and
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
665 incrementing by @var{separation}, and ending at or just before
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
666 @var{to}. @var{separation} can be positive or negative and defaults
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
667 to 1. If @var{to} is @code{nil} or numerically equal to @var{from},
60040
24dd4b5475b4 (List-related Predicates): Minor wording improvement.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
668 the value is the one-element list @code{(@var{from})}. If @var{to} is
24dd4b5475b4 (List-related Predicates): Minor wording improvement.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
669 less than @var{from} with a positive @var{separation}, or greater than
24dd4b5475b4 (List-related Predicates): Minor wording improvement.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
670 @var{from} with a negative @var{separation}, the value is @code{nil}
24dd4b5475b4 (List-related Predicates): Minor wording improvement.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
671 because those arguments specify an empty sequence.
24dd4b5475b4 (List-related Predicates): Minor wording improvement.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
672
24dd4b5475b4 (List-related Predicates): Minor wording improvement.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
673 If @var{separation} is 0 and @var{to} is neither @code{nil} nor
24dd4b5475b4 (List-related Predicates): Minor wording improvement.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
674 numerically equal to @var{from}, @code{number-sequence} signals an
24dd4b5475b4 (List-related Predicates): Minor wording improvement.
Richard M. Stallman <rms@gnu.org>
parents: 56215
diff changeset
675 error, since those arguments specify an infinite sequence.
53194
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
676
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
677 All arguments can be integers or floating point numbers. However,
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
678 floating point arguments can be tricky, because floating point
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
679 arithmetic is inexact. For instance, depending on the machine, it may
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
680 quite well happen that @code{(number-sequence 0.4 0.6 0.2)} returns
54945
70fd47f8342a Add anchors. Some other minor changes.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54264
diff changeset
681 the one element list @code{(0.4)}, whereas
53194
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
682 @code{(number-sequence 0.4 0.8 0.2)} returns a list with three
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
683 elements. The @var{n}th element of the list is computed by the exact
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
684 formula @code{(+ @var{from} (* @var{n} @var{separation}))}. Thus, if
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
685 one wants to make sure that @var{to} is included in the list, one can
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
686 pass an expression of this exact type for @var{to}. Alternatively,
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
687 one can replace @var{to} with a slightly larger value (or a slightly
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
688 more negative value if @var{separation} is negative).
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
689
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
690 Some examples:
52000
8aed6a3b153d (Building Lists): Add number-sequence.
Richard M. Stallman <rms@gnu.org>
parents: 51703
diff changeset
691
8aed6a3b153d (Building Lists): Add number-sequence.
Richard M. Stallman <rms@gnu.org>
parents: 51703
diff changeset
692 @example
8aed6a3b153d (Building Lists): Add number-sequence.
Richard M. Stallman <rms@gnu.org>
parents: 51703
diff changeset
693 (number-sequence 4 9)
8aed6a3b153d (Building Lists): Add number-sequence.
Richard M. Stallman <rms@gnu.org>
parents: 51703
diff changeset
694 @result{} (4 5 6 7 8 9)
53194
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
695 (number-sequence 9 4 -1)
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
696 @result{} (9 8 7 6 5 4)
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
697 (number-sequence 9 4 -2)
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
698 @result{} (9 7 5)
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
699 (number-sequence 8)
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
700 @result{} (8)
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
701 (number-sequence 8 5)
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
702 @result{} nil
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
703 (number-sequence 5 8 -1)
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
704 @result{} nil
52000
8aed6a3b153d (Building Lists): Add number-sequence.
Richard M. Stallman <rms@gnu.org>
parents: 51703
diff changeset
705 (number-sequence 1.5 6 2)
8aed6a3b153d (Building Lists): Add number-sequence.
Richard M. Stallman <rms@gnu.org>
parents: 51703
diff changeset
706 @result{} (1.5 3.5 5.5)
8aed6a3b153d (Building Lists): Add number-sequence.
Richard M. Stallman <rms@gnu.org>
parents: 51703
diff changeset
707 @end example
8aed6a3b153d (Building Lists): Add number-sequence.
Richard M. Stallman <rms@gnu.org>
parents: 51703
diff changeset
708 @end defun
8aed6a3b153d (Building Lists): Add number-sequence.
Richard M. Stallman <rms@gnu.org>
parents: 51703
diff changeset
709
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
710 @node Modifying Lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
711 @section Modifying Existing List Structure
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22253
diff changeset
712 @cindex destructive list operations
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
713
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
714 You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39200
diff changeset
715 primitives @code{setcar} and @code{setcdr}. We call these ``destructive''
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22253
diff changeset
716 operations because they change existing list structure.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
717
63590
ffe64a60452e (Rings): Various minor clarifications and corrections.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63541
diff changeset
718 @cindex CL note---@code{rplaca} vs @code{setcar}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
719 @quotation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
720 @findex rplaca
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
721 @findex rplacd
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
722 @b{Common Lisp note:} Common Lisp uses functions @code{rplaca} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
723 @code{rplacd} to alter list structure; they change structure the same
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
724 way as @code{setcar} and @code{setcdr}, but the Common Lisp functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
725 return the cons cell while @code{setcar} and @code{setcdr} return the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
726 new @sc{car} or @sc{cdr}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
727 @end quotation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
728
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
730 * Setcar:: Replacing an element in a list.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731 * Setcdr:: Replacing part of the list backbone.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732 This can be used to remove or add elements.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
733 * Rearrangement:: Reordering the elements in a list; combining lists.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
734 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
735
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
736 @node Setcar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
737 @subsection Altering List Elements with @code{setcar}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
738
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
739 Changing the @sc{car} of a cons cell is done with @code{setcar}. When
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
740 used on a list, @code{setcar} replaces one element of a list with a
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
741 different element.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
742
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
743 @defun setcar cons object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
744 This function stores @var{object} as the new @sc{car} of @var{cons},
22253
ed6b191416cf *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
745 replacing its previous @sc{car}. In other words, it changes the
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22961
diff changeset
746 @sc{car} slot of @var{cons} to refer to @var{object}. It returns the
22253
ed6b191416cf *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
747 value @var{object}. For example:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
748
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
749 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
750 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
751 (setq x '(1 2))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
752 @result{} (1 2)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
753 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
754 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
755 (setcar x 4)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
756 @result{} 4
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
757 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
758 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
759 x
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
760 @result{} (4 2)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
761 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
762 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
763 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
764
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
765 When a cons cell is part of the shared structure of several lists,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
766 storing a new @sc{car} into the cons changes one element of each of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
767 these lists. Here is an example:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
768
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
769 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
770 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
771 ;; @r{Create two lists that are partly shared.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
772 (setq x1 '(a b c))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
773 @result{} (a b c)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
774 (setq x2 (cons 'z (cdr x1)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
775 @result{} (z b c)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
776 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
777
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
778 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
779 ;; @r{Replace the @sc{car} of a shared link.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
780 (setcar (cdr x1) 'foo)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
781 @result{} foo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
782 x1 ; @r{Both lists are changed.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
783 @result{} (a foo c)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
784 x2
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
785 @result{} (z foo c)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
786 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
787
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
788 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
789 ;; @r{Replace the @sc{car} of a link that is not shared.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
790 (setcar x1 'baz)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
791 @result{} baz
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
792 x1 ; @r{Only one list is changed.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
793 @result{} (baz foo c)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
794 x2
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
795 @result{} (z foo c)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
796 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
797 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
798
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
799 Here is a graphical depiction of the shared structure of the two lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
800 in the variables @code{x1} and @code{x2}, showing why replacing @code{b}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
801 changes them both:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
802
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
803 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
804 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
805 --- --- --- --- --- ---
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
806 x1---> | | |----> | | |--> | | |--> nil
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
807 --- --- --- --- --- ---
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
808 | --> | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
809 | | | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
810 --> a | --> b --> c
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
811 |
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
812 --- --- |
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
813 x2--> | | |--
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
814 --- ---
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
815 |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
816 |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
817 --> z
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
818 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
819 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
820
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
821 Here is an alternative form of box diagram, showing the same relationship:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
822
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
823 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
824 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
825 x1:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
826 -------------- -------------- --------------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
827 | car | cdr | | car | cdr | | car | cdr |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
828 | a | o------->| b | o------->| c | nil |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
829 | | | -->| | | | | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
830 -------------- | -------------- --------------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
831 |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
832 x2: |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
833 -------------- |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
834 | car | cdr | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
835 | z | o----
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
836 | | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
837 --------------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
838 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
839 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
840
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
841 @node Setcdr
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
842 @subsection Altering the CDR of a List
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
843
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
844 The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
845
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
846 @defun setcdr cons object
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
847 This function stores @var{object} as the new @sc{cdr} of @var{cons},
22253
ed6b191416cf *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
848 replacing its previous @sc{cdr}. In other words, it changes the
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22961
diff changeset
849 @sc{cdr} slot of @var{cons} to refer to @var{object}. It returns the
22253
ed6b191416cf *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
850 value @var{object}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
851 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
852
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
853 Here is an example of replacing the @sc{cdr} of a list with a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
854 different list. All but the first element of the list are removed in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
855 favor of a different sequence of elements. The first element is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
856 unchanged, because it resides in the @sc{car} of the list, and is not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
857 reached via the @sc{cdr}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
858
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
859 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
861 (setq x '(1 2 3))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
862 @result{} (1 2 3)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
863 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
864 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
865 (setcdr x '(4))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
866 @result{} (4)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
867 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
868 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
869 x
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
870 @result{} (1 4)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
871 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
872 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
873
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
874 You can delete elements from the middle of a list by altering the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
875 @sc{cdr}s of the cons cells in the list. For example, here we delete
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
876 the second element, @code{b}, from the list @code{(a b c)}, by changing
22253
ed6b191416cf *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
877 the @sc{cdr} of the first cons cell:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
878
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
879 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
880 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
881 (setq x1 '(a b c))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
882 @result{} (a b c)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
883 (setcdr x1 (cdr (cdr x1)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
884 @result{} (c)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
885 x1
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
886 @result{} (a c)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
887 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
888 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
889
12282
586e3ea81792 updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
890 @need 4000
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
891 Here is the result in box notation:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
892
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
893 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
894 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
895 --------------------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
896 | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
897 -------------- | -------------- | --------------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
898 | car | cdr | | | car | cdr | -->| car | cdr |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
899 | a | o----- | b | o-------->| c | nil |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
900 | | | | | | | | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
901 -------------- -------------- --------------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
902 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
903 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
904
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
905 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
906 The second cons cell, which previously held the element @code{b}, still
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
907 exists and its @sc{car} is still @code{b}, but it no longer forms part
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
908 of this list.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
909
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
910 It is equally easy to insert a new element by changing @sc{cdr}s:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
911
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
912 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
913 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
914 (setq x1 '(a b c))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
915 @result{} (a b c)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
916 (setcdr x1 (cons 'd (cdr x1)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
917 @result{} (d b c)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
918 x1
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
919 @result{} (a d b c)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
920 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
921 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
922
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
923 Here is this result in box notation:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
924
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
925 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
926 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
927 -------------- ------------- -------------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
928 | car | cdr | | car | cdr | | car | cdr |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
929 | a | o | -->| b | o------->| c | nil |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
930 | | | | | | | | | | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
931 --------- | -- | ------------- -------------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
932 | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
933 ----- --------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
934 | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
935 | --------------- |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
936 | | car | cdr | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
937 -->| d | o------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
938 | | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
939 ---------------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
940 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
941 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
942
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
943 @node Rearrangement
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
944 @subsection Functions that Rearrange Lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
945 @cindex rearrangement of lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
946 @cindex modification of lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
947
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
948 Here are some functions that rearrange lists ``destructively'' by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
949 modifying the @sc{cdr}s of their component cons cells. We call these
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
950 functions ``destructive'' because they chew up the original lists passed
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22253
diff changeset
951 to them as arguments, relinking their cons cells to form a new list that
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22253
diff changeset
952 is the returned value.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
953
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
954 @ifnottex
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
955 See @code{delq}, in @ref{Sets And Lists}, for another function
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
956 that modifies cons cells.
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
957 @end ifnottex
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
958 @iftex
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
959 The function @code{delq} in the following section is another example
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
960 of destructive list manipulation.
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
961 @end iftex
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
962
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
963 @defun nconc &rest lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
964 @cindex concatenating lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
965 @cindex joining lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
966 This function returns a list containing all the elements of @var{lists}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
967 Unlike @code{append} (@pxref{Building Lists}), the @var{lists} are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
968 @emph{not} copied. Instead, the last @sc{cdr} of each of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
969 @var{lists} is changed to refer to the following list. The last of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
970 @var{lists} is not altered. For example:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
971
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
972 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
973 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
974 (setq x '(1 2 3))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
975 @result{} (1 2 3)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
976 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
977 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
978 (nconc x '(4 5))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
979 @result{} (1 2 3 4 5)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
980 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
981 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
982 x
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
983 @result{} (1 2 3 4 5)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
984 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
985 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
986
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
987 Since the last argument of @code{nconc} is not itself modified, it is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
988 reasonable to use a constant list, such as @code{'(4 5)}, as in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
989 above example. For the same reason, the last argument need not be a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
990 list:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
991
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
992 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
993 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
994 (setq x '(1 2 3))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
995 @result{} (1 2 3)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
996 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
997 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
998 (nconc x 'z)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
999 @result{} (1 2 3 . z)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1000 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1001 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1002 x
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1003 @result{} (1 2 3 . z)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1004 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1005 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1006
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1007 However, the other arguments (all but the last) must be lists.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1008
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1009 A common pitfall is to use a quoted constant list as a non-last
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1010 argument to @code{nconc}. If you do this, your program will change
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1011 each time you run it! Here is what happens:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1012
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1013 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1014 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1015 (defun add-foo (x) ; @r{We want this function to add}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1016 (nconc '(foo) x)) ; @r{@code{foo} to the front of its arg.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1017 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1018
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1019 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1020 (symbol-function 'add-foo)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1021 @result{} (lambda (x) (nconc (quote (foo)) x))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1022 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1023
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1024 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1025 (setq xx (add-foo '(1 2))) ; @r{It seems to work.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1026 @result{} (foo 1 2)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1027 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1028 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1029 (setq xy (add-foo '(3 4))) ; @r{What happened?}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1030 @result{} (foo 1 2 3 4)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1031 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1032 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1033 (eq xx xy)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1034 @result{} t
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1035 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1036
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1037 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1038 (symbol-function 'add-foo)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1039 @result{} (lambda (x) (nconc (quote (foo 1 2 3 4) x)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1040 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1041 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1042 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1043
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1044 @defun nreverse list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1045 @cindex reversing a list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1046 This function reverses the order of the elements of @var{list}.
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1047 Unlike @code{reverse}, @code{nreverse} alters its argument by reversing
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1048 the @sc{cdr}s in the cons cells forming the list. The cons cell that
22253
ed6b191416cf *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1049 used to be the last one in @var{list} becomes the first cons cell of the
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1050 value.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1051
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1052 For example:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1053
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1054 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1055 @group
38786
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
1056 (setq x '(a b c))
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
1057 @result{} (a b c)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1058 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1059 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1060 x
38786
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
1061 @result{} (a b c)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1062 (nreverse x)
38786
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
1063 @result{} (c b a)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1064 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1065 @group
22253
ed6b191416cf *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1066 ;; @r{The cons cell that was first is now last.}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1067 x
38786
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
1068 @result{} (a)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1069 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1070 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1071
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1072 To avoid confusion, we usually store the result of @code{nreverse}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1073 back in the same variable which held the original list:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1074
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1075 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1076 (setq x (nreverse x))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1077 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1078
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1079 Here is the @code{nreverse} of our favorite example, @code{(a b c)},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1080 presented graphically:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1081
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1082 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1083 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1084 @r{Original list head:} @r{Reversed list:}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1085 ------------- ------------- ------------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1086 | car | cdr | | car | cdr | | car | cdr |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1087 | a | nil |<-- | b | o |<-- | c | o |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1088 | | | | | | | | | | | | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1089 ------------- | --------- | - | -------- | -
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1090 | | | |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1091 ------------- ------------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1092 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1093 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1094 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1095
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1096 @defun sort list predicate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1097 @cindex stable sort
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1098 @cindex sorting lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1099 This function sorts @var{list} stably, though destructively, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1100 returns the sorted list. It compares elements using @var{predicate}. A
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1101 stable sort is one in which elements with equal sort keys maintain their
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1102 relative order before and after the sort. Stability is important when
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1103 successive sorts are used to order elements according to different
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1104 criteria.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1105
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1106 The argument @var{predicate} must be a function that accepts two
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1107 arguments. It is called with two elements of @var{list}. To get an
63604
4ca64c59b88b (Rearrangement): Sort predicate may just return non-nil.
Kim F. Storm <storm@cua.dk>
parents: 63590
diff changeset
1108 increasing order sort, the @var{predicate} should return non-@code{nil} if the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1109 first element is ``less than'' the second, or @code{nil} if not.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1110
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1111 The comparison function @var{predicate} must give reliable results for
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1112 any given pair of arguments, at least within a single call to
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1113 @code{sort}. It must be @dfn{antisymmetric}; that is, if @var{a} is
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1114 less than @var{b}, @var{b} must not be less than @var{a}. It must be
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1115 @dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b}
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1116 is less than @var{c}, then @var{a} must be less than @var{c}. If you
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1117 use a comparison function which does not meet these requirements, the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1118 result of @code{sort} is unpredictable.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1119
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1120 The destructive aspect of @code{sort} is that it rearranges the cons
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1121 cells forming @var{list} by changing @sc{cdr}s. A nondestructive sort
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1122 function would create new cons cells to store the elements in their
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1123 sorted order. If you wish to make a sorted copy without destroying the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1124 original, copy it first with @code{copy-sequence} and then sort.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1125
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1126 Sorting does not change the @sc{car}s of the cons cells in @var{list};
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1127 the cons cell that originally contained the element @code{a} in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1128 @var{list} still has @code{a} in its @sc{car} after sorting, but it now
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1129 appears in a different position in the list due to the change of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1130 @sc{cdr}s. For example:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1131
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1132 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1133 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1134 (setq nums '(1 3 2 6 5 4 0))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1135 @result{} (1 3 2 6 5 4 0)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1136 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1137 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1138 (sort nums '<)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1139 @result{} (0 1 2 3 4 5 6)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1140 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1141 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1142 nums
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1143 @result{} (1 2 3 4 5 6)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1144 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1145 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1146
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1147 @noindent
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13229
diff changeset
1148 @strong{Warning}: Note that the list in @code{nums} no longer contains
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13229
diff changeset
1149 0; this is the same cons cell that it was before, but it is no longer
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13229
diff changeset
1150 the first one in the list. Don't assume a variable that formerly held
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13229
diff changeset
1151 the argument now holds the entire sorted list! Instead, save the result
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13229
diff changeset
1152 of @code{sort} and use that. Most often we store the result back into
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13229
diff changeset
1153 the variable that held the original list:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1154
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1155 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1156 (setq nums (sort nums '<))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1157 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1158
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1159 @xref{Sorting}, for more functions that perform sorting.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1160 See @code{documentation} in @ref{Accessing Documentation}, for a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1161 useful example of @code{sort}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1162 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1163
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1164 @node Sets And Lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1165 @section Using Lists as Sets
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1166 @cindex lists as sets
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1167 @cindex sets
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1168
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1169 A list can represent an unordered mathematical set---simply consider a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1170 value an element of a set if it appears in the list, and ignore the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1171 order of the list. To form the union of two sets, use @code{append} (as
53644
5d6e643eb334 (Sets And Lists): Add delete-dups.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53428
diff changeset
1172 long as you don't mind having duplicate elements). You can remove
5d6e643eb334 (Sets And Lists): Add delete-dups.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53428
diff changeset
1173 @code{equal} duplicates using @code{delete-dups}. Other useful
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1174 functions for sets include @code{memq} and @code{delq}, and their
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1175 @code{equal} versions, @code{member} and @code{delete}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1176
13229
909eb45b146d Minor fixes.
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
1177 @cindex CL note---lack @code{union}, @code{intersection}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1178 @quotation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1179 @b{Common Lisp note:} Common Lisp has functions @code{union} (which
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1180 avoids duplicate elements) and @code{intersection} for set operations,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1181 but GNU Emacs Lisp does not have them. You can write them in Lisp if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1182 you wish.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1183 @end quotation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1184
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1185 @defun memq object list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1186 @cindex membership in a list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1187 This function tests to see whether @var{object} is a member of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1188 @var{list}. If it is, @code{memq} returns a list starting with the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1189 first occurrence of @var{object}. Otherwise, it returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1190 The letter @samp{q} in @code{memq} says that it uses @code{eq} to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1191 compare @var{object} against the elements of the list. For example:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1192
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1193 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1194 @group
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1195 (memq 'b '(a b c b a))
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1196 @result{} (b c b a)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1197 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1198 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1199 (memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1200 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1201 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1202 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1203 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1204
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1205 @defun delq object list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1206 @cindex deletion of elements
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1207 This function destructively removes all elements @code{eq} to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1208 @var{object} from @var{list}. The letter @samp{q} in @code{delq} says
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1209 that it uses @code{eq} to compare @var{object} against the elements of
30808
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1210 the list, like @code{memq} and @code{remq}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1211 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1212
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1213 When @code{delq} deletes elements from the front of the list, it does so
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1214 simply by advancing down the list and returning a sublist that starts
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1215 after those elements:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1216
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1217 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1218 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1219 (delq 'a '(a b c)) @equiv{} (cdr '(a b c))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1220 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1221 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1222
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1223 When an element to be deleted appears in the middle of the list,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1224 removing it involves changing the @sc{cdr}s (@pxref{Setcdr}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1225
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1226 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1227 @group
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1228 (setq sample-list '(a b c (4)))
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1229 @result{} (a b c (4))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1230 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1231 @group
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1232 (delq 'a sample-list)
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1233 @result{} (b c (4))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1234 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1235 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1236 sample-list
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1237 @result{} (a b c (4))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1238 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1239 @group
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1240 (delq 'c sample-list)
11628
ff046980f017 Fix delq example.
Richard M. Stallman <rms@gnu.org>
parents: 11137
diff changeset
1241 @result{} (a b (4))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1242 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1243 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1244 sample-list
11628
ff046980f017 Fix delq example.
Richard M. Stallman <rms@gnu.org>
parents: 11137
diff changeset
1245 @result{} (a b (4))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1246 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1247 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1248
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1249 Note that @code{(delq 'c sample-list)} modifies @code{sample-list} to
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1250 splice out the third element, but @code{(delq 'a sample-list)} does not
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1251 splice anything---it just returns a shorter list. Don't assume that a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1252 variable which formerly held the argument @var{list} now has fewer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1253 elements, or that it still holds the original list! Instead, save the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1254 result of @code{delq} and use that. Most often we store the result back
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1255 into the variable that held the original list:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1256
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1257 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1258 (setq flowers (delq 'rose flowers))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1259 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1260
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1261 In the following example, the @code{(4)} that @code{delq} attempts to match
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1262 and the @code{(4)} in the @code{sample-list} are not @code{eq}:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1263
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1264 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1265 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1266 (delq '(4) sample-list)
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1267 @result{} (a c (4))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1268 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1269 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1270
53428
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1271 @defun remq object list
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1272 This function returns a copy of @var{list}, with all elements removed
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1273 which are @code{eq} to @var{object}. The letter @samp{q} in @code{remq}
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1274 says that it uses @code{eq} to compare @var{object} against the elements
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1275 of @code{list}.
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1276
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1277 @example
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1278 @group
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1279 (setq sample-list '(a b c a b c))
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1280 @result{} (a b c a b c)
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1281 @end group
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1282 @group
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1283 (remq 'a sample-list)
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1284 @result{} (b c b c)
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1285 @end group
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1286 @group
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1287 sample-list
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1288 @result{} (a b c a b c)
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1289 @end group
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1290 @end example
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1291 @noindent
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1292 The function @code{delq} offers a way to perform this operation
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1293 destructively. See @ref{Sets And Lists}.
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1294 @end defun
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1295
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1296 The following three functions are like @code{memq}, @code{delq} and
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1297 @code{remq}, but use @code{equal} rather than @code{eq} to compare
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1298 elements. @xref{Equality Predicates}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1299
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1300 @defun member object list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1301 The function @code{member} tests to see whether @var{object} is a member
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1302 of @var{list}, comparing members with @var{object} using @code{equal}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1303 If @var{object} is a member, @code{member} returns a list starting with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1304 its first occurrence in @var{list}. Otherwise, it returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1305
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1306 Compare this with @code{memq}:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1307
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1308 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1309 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1310 (member '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are @code{equal}.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1311 @result{} ((2))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1312 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1313 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1314 (memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1315 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1316 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1317 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1318 ;; @r{Two strings with the same contents are @code{equal}.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1319 (member "foo" '("foo" "bar"))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1320 @result{} ("foo" "bar")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1321 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1322 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1323 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1324
30808
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1325 @defun delete object sequence
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1326 If @code{sequence} is a list, this function destructively removes all
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1327 elements @code{equal} to @var{object} from @var{sequence}. For lists,
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1328 @code{delete} is to @code{delq} as @code{member} is to @code{memq}: it
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1329 uses @code{equal} to compare elements with @var{object}, like
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1330 @code{member}; when it finds an element that matches, it removes the
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1331 element just as @code{delq} would.
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1332
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1333 If @code{sequence} is a vector or string, @code{delete} returns a copy
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1334 of @code{sequence} with all elements @code{equal} to @code{object}
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1335 removed.
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1336
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1337 For example:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1338
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1339 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1340 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1341 (delete '(2) '((2) (1) (2)))
13229
909eb45b146d Minor fixes.
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
1342 @result{} ((1))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1343 @end group
30808
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1344 @group
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1345 (delete '(2) [(2) (1) (2)])
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1346 @result{} [(1)]
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1347 @end group
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1348 @end example
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1349 @end defun
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1350
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1351 @defun remove object sequence
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1352 This function is the non-destructive counterpart of @code{delete}. If
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1353 returns a copy of @code{sequence}, a list, vector, or string, with
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1354 elements @code{equal} to @code{object} removed. For example:
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1355
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1356 @example
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1357 @group
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1358 (remove '(2) '((2) (1) (2)))
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1359 @result{} ((1))
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1360 @end group
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1361 @group
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1362 (remove '(2) [(2) (1) (2)])
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1363 @result{} [(1)]
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1364 @end group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1365 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1366 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1367
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1368 @quotation
30808
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1369 @b{Common Lisp note:} The functions @code{member}, @code{delete} and
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1370 @code{remove} in GNU Emacs Lisp are derived from Maclisp, not Common
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1371 Lisp. The Common Lisp versions do not use @code{equal} to compare
fa45a01185c0 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27332
diff changeset
1372 elements.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1373 @end quotation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1374
53194
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
1375 @defun member-ignore-case object list
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
1376 This function is like @code{member}, except that @var{object} should
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
1377 be a string and that it ignores differences in letter-case and text
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
1378 representation: upper-case and lower-case letters are treated as
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
1379 equal, and unibyte strings are converted to multibyte prior to
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
1380 comparison.
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
1381 @end defun
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
1382
53644
5d6e643eb334 (Sets And Lists): Add delete-dups.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53428
diff changeset
1383 @defun delete-dups list
5d6e643eb334 (Sets And Lists): Add delete-dups.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53428
diff changeset
1384 This function destructively removes all @code{equal} duplicates from
54047
291b91ef0840 (Sets And Lists): Update description of delete-dups.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54034
diff changeset
1385 @var{list}, stores the result in @var{list} and returns it. Of
291b91ef0840 (Sets And Lists): Update description of delete-dups.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54034
diff changeset
1386 several @code{equal} occurrences of an element in @var{list},
291b91ef0840 (Sets And Lists): Update description of delete-dups.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54034
diff changeset
1387 @code{delete-dups} keeps the first one.
53644
5d6e643eb334 (Sets And Lists): Add delete-dups.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53428
diff changeset
1388 @end defun
5d6e643eb334 (Sets And Lists): Add delete-dups.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53428
diff changeset
1389
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1390 See also the function @code{add-to-list}, in @ref{Setting Variables},
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1391 for another way to add an element to a list stored in a variable.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1392
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1393 @node Association Lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1394 @section Association Lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1395 @cindex association list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1396 @cindex alist
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1397
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1398 An @dfn{association list}, or @dfn{alist} for short, records a mapping
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1399 from keys to values. It is a list of cons cells called
22253
ed6b191416cf *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1400 @dfn{associations}: the @sc{car} of each cons cell is the @dfn{key}, and the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1401 @sc{cdr} is the @dfn{associated value}.@footnote{This usage of ``key''
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1402 is not related to the term ``key sequence''; it means a value used to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1403 look up an item in a table. In this case, the table is the alist, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1404 the alist associations are the items.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1405
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1406 Here is an example of an alist. The key @code{pine} is associated with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1407 the value @code{cones}; the key @code{oak} is associated with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1408 @code{acorns}; and the key @code{maple} is associated with @code{seeds}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1409
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1410 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1411 @group
38786
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
1412 ((pine . cones)
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
1413 (oak . acorns)
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
1414 (maple . seeds))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1415 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1416 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1417
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1418 The associated values in an alist may be any Lisp objects; so may the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1419 keys. For example, in the following alist, the symbol @code{a} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1420 associated with the number @code{1}, and the string @code{"b"} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1421 associated with the @emph{list} @code{(2 3)}, which is the @sc{cdr} of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1422 the alist element:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1423
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1424 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1425 ((a . 1) ("b" 2 3))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1426 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1427
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1428 Sometimes it is better to design an alist to store the associated
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1429 value in the @sc{car} of the @sc{cdr} of the element. Here is an
38786
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
1430 example of such an alist:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1431
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1432 @example
38786
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
1433 ((rose red) (lily white) (buttercup yellow))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1434 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1435
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1436 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1437 Here we regard @code{red} as the value associated with @code{rose}. One
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13229
diff changeset
1438 advantage of this kind of alist is that you can store other related
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1439 information---even a list of other items---in the @sc{cdr} of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1440 @sc{cdr}. One disadvantage is that you cannot use @code{rassq} (see
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1441 below) to find the element containing a given value. When neither of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1442 these considerations is important, the choice is a matter of taste, as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1443 long as you are consistent about it for any given alist.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1444
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1445 Note that the same alist shown above could be regarded as having the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1446 associated value in the @sc{cdr} of the element; the value associated
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1447 with @code{rose} would be the list @code{(red)}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1448
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1449 Association lists are often used to record information that you might
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1450 otherwise keep on a stack, since new associations may be added easily to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1451 the front of the list. When searching an association list for an
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1452 association with a given key, the first one found is returned, if there
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1453 is more than one.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1454
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1455 In Emacs Lisp, it is @emph{not} an error if an element of an
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1456 association list is not a cons cell. The alist search functions simply
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1457 ignore such elements. Many other versions of Lisp signal errors in such
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1458 cases.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1459
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1460 Note that property lists are similar to association lists in several
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1461 respects. A property list behaves like an association list in which
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1462 each key can occur only once. @xref{Property Lists}, for a comparison
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1463 of property lists and association lists.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1464
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1465 @defun assoc key alist
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1466 This function returns the first association for @var{key} in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1467 @var{alist}. It compares @var{key} against the alist elements using
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1468 @code{equal} (@pxref{Equality Predicates}). It returns @code{nil} if no
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1469 association in @var{alist} has a @sc{car} @code{equal} to @var{key}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1470 For example:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1471
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1472 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1473 (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1474 @result{} ((pine . cones) (oak . acorns) (maple . seeds))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1475 (assoc 'oak trees)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1476 @result{} (oak . acorns)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1477 (cdr (assoc 'oak trees))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1478 @result{} acorns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1479 (assoc 'birch trees)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1480 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1481 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1482
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1483 Here is another example, in which the keys and values are not symbols:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1484
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1485 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1486 (setq needles-per-cluster
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1487 '((2 "Austrian Pine" "Red Pine")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1488 (3 "Pitch Pine")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1489 (5 "White Pine")))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1490
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1491 (cdr (assoc 3 needles-per-cluster))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1492 @result{} ("Pitch Pine")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1493 (cdr (assoc 2 needles-per-cluster))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1494 @result{} ("Austrian Pine" "Red Pine")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1495 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1496 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1497
53428
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1498 The function @code{assoc-string} is much like @code{assoc} except
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1499 that it ignores certain differences between strings. @xref{Text
ccd937cd7241 (Building Lists): remq moved elsewhere.
Richard M. Stallman <rms@gnu.org>
parents: 53194
diff changeset
1500 Comparison}.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1501
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11628
diff changeset
1502 @defun rassoc value alist
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11628
diff changeset
1503 This function returns the first association with value @var{value} in
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11628
diff changeset
1504 @var{alist}. It returns @code{nil} if no association in @var{alist} has
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11628
diff changeset
1505 a @sc{cdr} @code{equal} to @var{value}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11628
diff changeset
1506
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11628
diff changeset
1507 @code{rassoc} is like @code{assoc} except that it compares the @sc{cdr} of
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11628
diff changeset
1508 each @var{alist} association instead of the @sc{car}. You can think of
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11628
diff changeset
1509 this as ``reverse @code{assoc}'', finding the key for a given value.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11628
diff changeset
1510 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11628
diff changeset
1511
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1512 @defun assq key alist
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1513 This function is like @code{assoc} in that it returns the first
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1514 association for @var{key} in @var{alist}, but it makes the comparison
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1515 using @code{eq} instead of @code{equal}. @code{assq} returns @code{nil}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1516 if no association in @var{alist} has a @sc{car} @code{eq} to @var{key}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1517 This function is used more often than @code{assoc}, since @code{eq} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1518 faster than @code{equal} and most alists use symbols as keys.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1519 @xref{Equality Predicates}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1520
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1521 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1522 (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1523 @result{} ((pine . cones) (oak . acorns) (maple . seeds))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1524 (assq 'pine trees)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1525 @result{} (pine . cones)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1526 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1527
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1528 On the other hand, @code{assq} is not usually useful in alists where the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1529 keys may not be symbols:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1530
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1531 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1532 (setq leaves
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1533 '(("simple leaves" . oak)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1534 ("compound leaves" . horsechestnut)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1535
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1536 (assq "simple leaves" leaves)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1537 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1538 (assoc "simple leaves" leaves)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1539 @result{} ("simple leaves" . oak)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1540 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1541 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1542
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1543 @defun rassq value alist
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1544 This function returns the first association with value @var{value} in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1545 @var{alist}. It returns @code{nil} if no association in @var{alist} has
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1546 a @sc{cdr} @code{eq} to @var{value}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1547
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1548 @code{rassq} is like @code{assq} except that it compares the @sc{cdr} of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1549 each @var{alist} association instead of the @sc{car}. You can think of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1550 this as ``reverse @code{assq}'', finding the key for a given value.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1551
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1552 For example:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1553
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1554 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1555 (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1556
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1557 (rassq 'acorns trees)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1558 @result{} (oak . acorns)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1559 (rassq 'spores trees)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1560 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1561 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1562
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1563 Note that @code{rassq} cannot search for a value stored in the @sc{car}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1564 of the @sc{cdr} of an element:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1565
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1566 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1567 (setq colors '((rose red) (lily white) (buttercup yellow)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1568
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1569 (rassq 'white colors)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1570 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1571 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1572
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1573 In this case, the @sc{cdr} of the association @code{(lily white)} is not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1574 the symbol @code{white}, but rather the list @code{(white)}. This
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1575 becomes clearer if the association is written in dotted pair notation:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1576
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1577 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1578 (lily white) @equiv{} (lily . (white))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1579 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1580 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1581
38786
4d3fd773cd30 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 36900
diff changeset
1582 @defun assoc-default key alist &optional test default
22961
8159553e2468 Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
1583 This function searches @var{alist} for a match for @var{key}. For each
8159553e2468 Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
1584 element of @var{alist}, it compares the element (if it is an atom) or
8159553e2468 Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
1585 the element's @sc{car} (if it is a cons) against @var{key}, by calling
8159553e2468 Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
1586 @var{test} with two arguments: the element or its @sc{car}, and
8159553e2468 Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
1587 @var{key}. The arguments are passed in that order so that you can get
8159553e2468 Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
1588 useful results using @code{string-match} with an alist that contains
8159553e2468 Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
1589 regular expressions (@pxref{Regexp Search}). If @var{test} is omitted
8159553e2468 Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
1590 or @code{nil}, @code{equal} is used for comparison.
8159553e2468 Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
1591
8159553e2468 Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
1592 If an alist element matches @var{key} by this criterion,
8159553e2468 Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
1593 then @code{assoc-default} returns a value based on this element.
8159553e2468 Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
1594 If the element is a cons, then the value is the element's @sc{cdr}.
8159553e2468 Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
1595 Otherwise, the return value is @var{default}.
8159553e2468 Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
1596
8159553e2468 Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
1597 If no alist element matches @var{key}, @code{assoc-default} returns
8159553e2468 Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
1598 @code{nil}.
8159553e2468 Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
1599 @end defun
8159553e2468 Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents: 22274
diff changeset
1600
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1601 @defun copy-alist alist
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1602 @cindex copying alists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1603 This function returns a two-level deep copy of @var{alist}: it creates a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1604 new copy of each association, so that you can alter the associations of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1605 the new alist without changing the old one.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1606
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1607 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1608 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1609 (setq needles-per-cluster
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1610 '((2 . ("Austrian Pine" "Red Pine"))
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1611 (3 . ("Pitch Pine"))
7734
2d4db32cccd5 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7337
diff changeset
1612 @end group
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1613 (5 . ("White Pine"))))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1614 @result{}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1615 ((2 "Austrian Pine" "Red Pine")
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1616 (3 "Pitch Pine")
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1617 (5 "White Pine"))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1618
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1619 (setq copy (copy-alist needles-per-cluster))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1620 @result{}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1621 ((2 "Austrian Pine" "Red Pine")
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1622 (3 "Pitch Pine")
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1623 (5 "White Pine"))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1624
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1625 (eq needles-per-cluster copy)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1626 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1627 (equal needles-per-cluster copy)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1628 @result{} t
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1629 (eq (car needles-per-cluster) (car copy))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1630 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1631 (cdr (car (cdr needles-per-cluster)))
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1632 @result{} ("Pitch Pine")
7734
2d4db32cccd5 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7337
diff changeset
1633 @group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1634 (eq (cdr (car (cdr needles-per-cluster)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1635 (cdr (car (cdr copy))))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1636 @result{} t
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1637 @end group
7337
cd57cd335fff *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7118
diff changeset
1638 @end smallexample
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1639
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1640 This example shows how @code{copy-alist} makes it possible to change
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1641 the associations of one copy without affecting the other:
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1642
7337
cd57cd335fff *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7118
diff changeset
1643 @smallexample
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1644 @group
11137
206af14bcffa Fix setcdr example.
Richard M. Stallman <rms@gnu.org>
parents: 7734
diff changeset
1645 (setcdr (assq 3 copy) '("Martian Vacuum Pine"))
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1646 (cdr (assq 3 needles-per-cluster))
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1647 @result{} ("Pitch Pine")
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1648 @end group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1649 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1650 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1651
36872
da90c393ed4e assq-delete-all <- assoc-delete-all
Dave Love <fx@gnu.org>
parents: 35090
diff changeset
1652 @defun assq-delete-all key alist
da90c393ed4e assq-delete-all <- assoc-delete-all
Dave Love <fx@gnu.org>
parents: 35090
diff changeset
1653 @tindex assq-delete-all
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
1654 This function deletes from @var{alist} all the elements whose @sc{car}
52694
3c9835a0d5b4 (Association Lists): Clarify `assq-delete-all'.
Richard M. Stallman <rms@gnu.org>
parents: 52484
diff changeset
1655 is @code{eq} to @var{key}, much as if you used @code{delq} to delete
53194
6bf4cf44dfb7 (Building Lists): `append' no longer accepts integer arguments.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52694
diff changeset
1656 each such element one by one. It returns the shortened alist, and
52694
3c9835a0d5b4 (Association Lists): Clarify `assq-delete-all'.
Richard M. Stallman <rms@gnu.org>
parents: 52484
diff changeset
1657 often modifies the original list structure of @var{alist}. For
3c9835a0d5b4 (Association Lists): Clarify `assq-delete-all'.
Richard M. Stallman <rms@gnu.org>
parents: 52484
diff changeset
1658 correct results, use the return value of @code{assq-delete-all} rather
3c9835a0d5b4 (Association Lists): Clarify `assq-delete-all'.
Richard M. Stallman <rms@gnu.org>
parents: 52484
diff changeset
1659 than looking at the saved value of @var{alist}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1660
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
1661 @example
52694
3c9835a0d5b4 (Association Lists): Clarify `assq-delete-all'.
Richard M. Stallman <rms@gnu.org>
parents: 52484
diff changeset
1662 (setq alist '((foo 1) (bar 2) (foo 3) (lose 4)))
3c9835a0d5b4 (Association Lists): Clarify `assq-delete-all'.
Richard M. Stallman <rms@gnu.org>
parents: 52484
diff changeset
1663 @result{} ((foo 1) (bar 2) (foo 3) (lose 4))
3c9835a0d5b4 (Association Lists): Clarify `assq-delete-all'.
Richard M. Stallman <rms@gnu.org>
parents: 52484
diff changeset
1664 (assq-delete-all 'foo alist)
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
1665 @result{} ((bar 2) (lose 4))
52694
3c9835a0d5b4 (Association Lists): Clarify `assq-delete-all'.
Richard M. Stallman <rms@gnu.org>
parents: 52484
diff changeset
1666 alist
3c9835a0d5b4 (Association Lists): Clarify `assq-delete-all'.
Richard M. Stallman <rms@gnu.org>
parents: 52484
diff changeset
1667 @result{} ((foo 1) (bar 2) (lose 4))
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
1668 @end example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
1669 @end defun
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52000
diff changeset
1670
61718
beeb90a3315c (Association Lists): Document rassq-delete-all.
Lute Kamstra <lute@gnu.org>
parents: 60448
diff changeset
1671 @defun rassq-delete-all value alist
beeb90a3315c (Association Lists): Document rassq-delete-all.
Lute Kamstra <lute@gnu.org>
parents: 60448
diff changeset
1672 This function deletes from @var{alist} all the elements whose @sc{cdr}
beeb90a3315c (Association Lists): Document rassq-delete-all.
Lute Kamstra <lute@gnu.org>
parents: 60448
diff changeset
1673 is @code{eq} to @var{value}. It returns the shortened alist, and
beeb90a3315c (Association Lists): Document rassq-delete-all.
Lute Kamstra <lute@gnu.org>
parents: 60448
diff changeset
1674 often modifies the original list structure of @var{alist}.
beeb90a3315c (Association Lists): Document rassq-delete-all.
Lute Kamstra <lute@gnu.org>
parents: 60448
diff changeset
1675 @code{rassq-delete-all} is like @code{assq-delete-all} except that it
beeb90a3315c (Association Lists): Document rassq-delete-all.
Lute Kamstra <lute@gnu.org>
parents: 60448
diff changeset
1676 compares the @sc{cdr} of each @var{alist} association instead of the
beeb90a3315c (Association Lists): Document rassq-delete-all.
Lute Kamstra <lute@gnu.org>
parents: 60448
diff changeset
1677 @sc{car}.
beeb90a3315c (Association Lists): Document rassq-delete-all.
Lute Kamstra <lute@gnu.org>
parents: 60448
diff changeset
1678 @end defun
beeb90a3315c (Association Lists): Document rassq-delete-all.
Lute Kamstra <lute@gnu.org>
parents: 60448
diff changeset
1679
63541
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1680 @node Rings
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1681 @section Managing a Fixed-Size Ring of Objects
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1682
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1683 @cindex ring data structure
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1684 This section describes functions for operating on rings. A
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1685 @dfn{ring} is a fixed-size data structure that supports insertion,
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1686 deletion, rotation, and modulo-indexed reference and traversal.
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1687
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1688 @defun make-ring size
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1689 This returns a new ring capable of holding @var{size} objects.
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1690 @var{size} should be an integer.
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1691 @end defun
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1692
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1693 @defun ring-p object
63590
ffe64a60452e (Rings): Various minor clarifications and corrections.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63541
diff changeset
1694 This returns @code{t} if @var{object} is a ring, @code{nil} otherwise.
63541
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1695 @end defun
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1696
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1697 @defun ring-size ring
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1698 This returns the maximum capacity of the @var{ring}.
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1699 @end defun
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1700
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1701 @defun ring-length ring
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1702 This returns the number of objects that @var{ring} currently contains.
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1703 The value will never exceed that returned by @code{ring-size}.
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1704 @end defun
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1705
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1706 @defun ring-elements ring
63729
d667a89621c9 (Rings): `ring-elements' now returns the elements of RING in order.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63604
diff changeset
1707 This returns a list of the objects in @var{ring}, in order, newest first.
63541
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1708 @end defun
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1709
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1710 @defun ring-copy ring
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1711 This returns a new ring which is a copy of @var{ring}.
63590
ffe64a60452e (Rings): Various minor clarifications and corrections.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63541
diff changeset
1712 The new ring contains the same (@code{eq}) objects as @var{ring}.
63541
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1713 @end defun
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1714
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1715 @defun ring-empty-p ring
63590
ffe64a60452e (Rings): Various minor clarifications and corrections.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63541
diff changeset
1716 This returns @code{t} if @var{ring} is empty, @code{nil} otherwise.
63541
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1717 @end defun
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1718
63590
ffe64a60452e (Rings): Various minor clarifications and corrections.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63541
diff changeset
1719 The newest element in the ring always has index 0. Higher indices
ffe64a60452e (Rings): Various minor clarifications and corrections.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63541
diff changeset
1720 correspond to older elements. Indices are computed modulo the ring
ffe64a60452e (Rings): Various minor clarifications and corrections.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63541
diff changeset
1721 length. Index @minus{}1 corresponds to the oldest element, @minus{}2
ffe64a60452e (Rings): Various minor clarifications and corrections.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63541
diff changeset
1722 to the next-oldest, and so forth.
63541
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1723
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1724 @defun ring-ref ring index
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1725 This returns the object in @var{ring} found at index @var{index}.
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1726 @var{index} may be negative or greater than the ring length. If
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1727 @var{ring} is empty, @code{ring-ref} signals an error.
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1728 @end defun
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1729
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1730 @defun ring-insert ring object
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1731 This inserts @var{object} into @var{ring}, making it the newest
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1732 element, and returns @var{object}.
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1733
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1734 If the ring is full, insertion removes the oldest element to
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1735 make room for the new element.
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1736 @end defun
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1737
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1738 @defun ring-remove ring &optional index
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1739 Remove an object from @var{ring}, and return that object. The
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1740 argument @var{index} specifies which item to remove; if it is
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1741 @code{nil}, that means to remove the oldest item. If @var{ring} is
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1742 empty, @code{ring-remove} signals an error.
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1743 @end defun
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1744
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1745 @defun ring-insert-at-beginning ring object
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1746 This inserts @var{object} into @var{ring}, treating it as the oldest
63590
ffe64a60452e (Rings): Various minor clarifications and corrections.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63541
diff changeset
1747 element. The return value is not significant.
63541
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1748
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1749 If the ring is full, this function removes the newest element to make
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1750 room for the inserted element.
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1751 @end defun
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1752
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1753 @cindex fifo data structure
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1754 If you are careful not to exceed the ring size, you can
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1755 use the ring as a first-in-first-out queue. For example:
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1756
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1757 @lisp
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1758 (let ((fifo (make-ring 5)))
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1759 (mapc (lambda (obj) (ring-insert fifo obj))
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1760 '(0 one "two"))
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1761 (list (ring-remove fifo) t
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1762 (ring-remove fifo) t
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1763 (ring-remove fifo)))
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1764 @result{} (0 t one t "two")
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1765 @end lisp
ddec16fed4a2 (Rings): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61718
diff changeset
1766
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52000
diff changeset
1767 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52000
diff changeset
1768 arch-tag: 31fb8a4e-4aa8-4a74-a206-aa00451394d4
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52000
diff changeset
1769 @end ignore