annotate lispref/lists.texi @ 56026:bb6720f21c54

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