annotate lispref/sequences.texi @ 74368:3fed121bb58a

** rgm@gnu.org, Nov 29: mouse and horizontal scrolling with long lines Fixed.
author Chong Yidong <cyd@stupidchicken.com>
date Sat, 02 Dec 2006 21:48:43 +0000
parents ab0f03398450
children 6d19c76d81c5 858cb33ae39d
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
64889
e836425ee789 Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 64723
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
68648
067115a6e738 Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 64889
diff changeset
4 @c 2004, 2005, 2006 Free Software Foundation, Inc.
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @setfilename ../info/sequences
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
7 @node Sequences Arrays Vectors, Hash Tables, Lists, Top
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @chapter Sequences, Arrays, and Vectors
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9 @cindex sequence
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
11 Recall that the @dfn{sequence} type is the union of two other Lisp
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
12 types: lists and arrays. In other words, any list is a sequence, and
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
13 any array is a sequence. The common property that all sequences have is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
14 that each is an ordered collection of elements.
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
16 An @dfn{array} is a single primitive object that has a slot for each
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
17 of its elements. All the elements are accessible in constant time, but
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
18 the length of an existing array cannot be changed. Strings, vectors,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
19 char-tables and bool-vectors are the four types of arrays.
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
20
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
21 A list is a sequence of elements, but it is not a single primitive
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
22 object; it is made of cons cells, one cell per element. Finding the
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
23 @var{n}th element requires looking through @var{n} cons cells, so
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
24 elements farther from the beginning of the list take longer to access.
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
25 But it is possible to add elements to the list, or remove elements.
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27 The following diagram shows the relationship between these types:
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
31 _____________________________________________
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
32 | |
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
33 | Sequence |
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
34 | ______ ________________________________ |
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
35 | | | | | |
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
36 | | List | | Array | |
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
37 | | | | ________ ________ | |
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
38 | |______| | | | | | | |
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
39 | | | Vector | | String | | |
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
40 | | |________| |________| | |
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
41 | | ____________ _____________ | |
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
42 | | | | | | | |
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
43 | | | Char-table | | Bool-vector | | |
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
44 | | |____________| |_____________| | |
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
45 | |________________________________| |
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
46 |_____________________________________________|
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50 The elements of vectors and lists may be any Lisp objects. The
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
51 elements of strings are all characters.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53 @menu
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
54 * Sequence Functions:: Functions that accept any kind of sequence.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55 * Arrays:: Characteristics of arrays in Emacs Lisp.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56 * Array Functions:: Functions specifically for arrays.
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
57 * Vectors:: Special characteristics of Emacs Lisp vectors.
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
58 * Vector Functions:: Functions specifically for vectors.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
59 * Char-Tables:: How to work with char-tables.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
60 * Bool-Vectors:: How to work with bool-vectors.
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 @end menu
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63 @node Sequence Functions
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64 @section Sequences
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
66 In Emacs Lisp, a @dfn{sequence} is either a list or an array. The
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
67 common property of all sequences is that they are ordered collections of
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
68 elements. This section describes functions that accept any kind of
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
69 sequence.
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
70
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
71 @defun sequencep object
54946
dc1950724cd9 Various clarifications.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54479
diff changeset
72 Returns @code{t} if @var{object} is a list, vector, string,
dc1950724cd9 Various clarifications.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54479
diff changeset
73 bool-vector, or char-table, @code{nil} otherwise.
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
76 @defun length sequence
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
77 @cindex string length
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
78 @cindex list length
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
79 @cindex vector length
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
80 @cindex sequence length
52787
785941182067 Char-tables are sequences.
Dave Love <fx@gnu.org>
parents: 52401
diff changeset
81 @cindex char-table length
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
82 This function returns the number of elements in @var{sequence}. If
54946
dc1950724cd9 Various clarifications.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54479
diff changeset
83 @var{sequence} is a dotted list, a @code{wrong-type-argument} error is
dc1950724cd9 Various clarifications.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54479
diff changeset
84 signaled. Circular lists may cause an infinite loop. For a
dc1950724cd9 Various clarifications.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54479
diff changeset
85 char-table, the value returned is always one more than the maximum
dc1950724cd9 Various clarifications.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54479
diff changeset
86 Emacs character code.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
87
54946
dc1950724cd9 Various clarifications.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54479
diff changeset
88 @xref{Definition of safe-length}, for the related function @code{safe-length}.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
89
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
90 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
91 @group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
92 (length '(1 2 3))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
93 @result{} 3
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
94 @end group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
95 @group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
96 (length ())
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
97 @result{} 0
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
98 @end group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
99 @group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
100 (length "foobar")
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
101 @result{} 6
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
102 @end group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
103 @group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
104 (length [1 2 3])
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
105 @result{} 3
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
106 @end group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
107 @group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
108 (length (make-bool-vector 5 nil))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
109 @result{} 5
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
110 @end group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
111 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
112 @end defun
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
113
52787
785941182067 Char-tables are sequences.
Dave Love <fx@gnu.org>
parents: 52401
diff changeset
114 @defun string-bytes string
785941182067 Char-tables are sequences.
Dave Love <fx@gnu.org>
parents: 52401
diff changeset
115 @cindex string, number of bytes
785941182067 Char-tables are sequences.
Dave Love <fx@gnu.org>
parents: 52401
diff changeset
116 This function returns the number of bytes in @var{string}.
785941182067 Char-tables are sequences.
Dave Love <fx@gnu.org>
parents: 52401
diff changeset
117 If @var{string} is a multibyte string, this is greater than
785941182067 Char-tables are sequences.
Dave Love <fx@gnu.org>
parents: 52401
diff changeset
118 @code{(length @var{string})}.
785941182067 Char-tables are sequences.
Dave Love <fx@gnu.org>
parents: 52401
diff changeset
119 @end defun
785941182067 Char-tables are sequences.
Dave Love <fx@gnu.org>
parents: 52401
diff changeset
120
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
121 @defun elt sequence index
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
122 @cindex elements of sequences
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
123 This function returns the element of @var{sequence} indexed by
54946
dc1950724cd9 Various clarifications.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54479
diff changeset
124 @var{index}. Legitimate values of @var{index} are integers ranging
dc1950724cd9 Various clarifications.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54479
diff changeset
125 from 0 up to one less than the length of @var{sequence}. If
dc1950724cd9 Various clarifications.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54479
diff changeset
126 @var{sequence} is a list, out-of-range values behave as for
dc1950724cd9 Various clarifications.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54479
diff changeset
127 @code{nth}. @xref{Definition of nth}. Otherwise, out-of-range values
dc1950724cd9 Various clarifications.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54479
diff changeset
128 trigger an @code{args-out-of-range} error.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
129
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
130 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
131 @group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
132 (elt [1 2 3 4] 2)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
133 @result{} 3
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
134 @end group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
135 @group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
136 (elt '(1 2 3 4) 2)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
137 @result{} 3
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
138 @end group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
139 @group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
140 ;; @r{We use @code{string} to show clearly which character @code{elt} returns.}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
141 (string (elt "1234" 2))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
142 @result{} "3"
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
143 @end group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
144 @group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
145 (elt [1 2 3 4] 4)
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
146 @error{} Args out of range: [1 2 3 4], 4
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
147 @end group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
148 @group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
149 (elt [1 2 3 4] -1)
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
150 @error{} Args out of range: [1 2 3 4], -1
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
151 @end group
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
152 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
153
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
154 This function generalizes @code{aref} (@pxref{Array Functions}) and
54946
dc1950724cd9 Various clarifications.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54479
diff changeset
155 @code{nth} (@pxref{Definition of nth}).
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
156 @end defun
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
157
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158 @defun copy-sequence sequence
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
159 @cindex copying sequences
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160 Returns a copy of @var{sequence}. The copy is the same type of object
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 as the original sequence, and it has the same elements in the same order.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163 Storing a new element into the copy does not affect the original
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164 @var{sequence}, and vice versa. However, the elements of the new
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
165 sequence are not copies; they are identical (@code{eq}) to the elements
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
166 of the original. Therefore, changes made within these elements, as
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167 found via the copied sequence, are also visible in the original
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
168 sequence.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170 If the sequence is a string with text properties, the property list in
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171 the copy is itself a copy, not shared with the original's property
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
172 list. However, the actual values of the properties are shared.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173 @xref{Text Properties}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174
54946
dc1950724cd9 Various clarifications.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54479
diff changeset
175 This function does not work for dotted lists. Trying to copy a
dc1950724cd9 Various clarifications.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54479
diff changeset
176 circular list may cause an infinite loop.
dc1950724cd9 Various clarifications.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54479
diff changeset
177
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178 See also @code{append} in @ref{Building Lists}, @code{concat} in
54479
3839917a7e9e (Sequence Functions): Replace xref to `Vectors' with `Vector Functions'.
Juri Linkov <juri@jurta.org>
parents: 52978
diff changeset
179 @ref{Creating Strings}, and @code{vconcat} in @ref{Vector Functions},
3839917a7e9e (Sequence Functions): Replace xref to `Vectors' with `Vector Functions'.
Juri Linkov <juri@jurta.org>
parents: 52978
diff changeset
180 for other ways to copy sequences.
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
183 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184 (setq bar '(1 2))
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
185 @result{} (1 2)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
187 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188 (setq x (vector 'foo bar))
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
189 @result{} [foo (1 2)]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
190 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
191 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192 (setq y (copy-sequence x))
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193 @result{} [foo (1 2)]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
194 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
195
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
196 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
197 (eq x y)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
198 @result{} nil
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
199 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
200 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
201 (equal x y)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202 @result{} t
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
203 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
204 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205 (eq (elt x 1) (elt y 1))
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
206 @result{} t
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
207 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
208
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210 ;; @r{Replacing an element of one sequence.}
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
211 (aset x 0 'quux)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
212 x @result{} [quux (1 2)]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213 y @result{} [foo (1 2)]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
217 ;; @r{Modifying the inside of a shared element.}
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218 (setcar (aref x 1) 69)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219 x @result{} [quux (69 2)]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220 y @result{} [foo (69 2)]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225 @node Arrays
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226 @section Arrays
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227 @cindex array
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
229 An @dfn{array} object has slots that hold a number of other Lisp
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 objects, called the elements of the array. Any element of an array may
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231 be accessed in constant time. In contrast, an element of a list
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232 requires access time that is proportional to the position of the element
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
233 in the list.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
234
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
235 Emacs defines four types of array, all one-dimensional: @dfn{strings},
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
236 @dfn{vectors}, @dfn{bool-vectors} and @dfn{char-tables}. A vector is a
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
237 general array; its elements can be any Lisp objects. A string is a
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 38941
diff changeset
238 specialized array; its elements must be characters. Each type of array
26254
a393c5e46e99 *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26239
diff changeset
239 has its own read syntax.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
240 @xref{String Type}, and @ref{Vector Type}.
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
242 All four kinds of array share these characteristics:
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244 @itemize @bullet
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245 @item
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246 The first element of an array has index zero, the second element has
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 index 1, and so on. This is called @dfn{zero-origin} indexing. For
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248 example, an array of four elements has indices 0, 1, 2, @w{and 3}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 @item
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
251 The length of the array is fixed once you create it; you cannot
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
252 change the length of an existing array.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
253
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
254 @item
64723
395915a45f02 Fix typo.
Juanma Barranquero <lekktu@gmail.com>
parents: 60271
diff changeset
255 For purposes of evaluation, the array is a constant---in other words,
60271
abb79c0e47ac (Arrays): Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 54946
diff changeset
256 it evaluates to itself.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
257
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
258 @item
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259 The elements of an array may be referenced or changed with the functions
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260 @code{aref} and @code{aset}, respectively (@pxref{Array Functions}).
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 @end itemize
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
263 When you create an array, other than a char-table, you must specify
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
264 its length. You cannot specify the length of a char-table, because that
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
265 is determined by the range of character codes.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
266
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
267 In principle, if you want an array of text characters, you could use
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
268 either a string or a vector. In practice, we always choose strings for
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
269 such applications, for four reasons:
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 @itemize @bullet
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 @item
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273 They occupy one-fourth the space of a vector of the same elements.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275 @item
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276 Strings are printed in a way that shows the contents more clearly
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
277 as text.
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 @item
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280 Strings can hold text properties. @xref{Text Properties}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282 @item
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283 Many of the specialized editing and I/O facilities of Emacs accept only
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284 strings. For example, you cannot insert a vector of characters into a
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285 buffer the way you can insert a string. @xref{Strings and Characters}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286 @end itemize
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
288 By contrast, for an array of keyboard input characters (such as a key
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
289 sequence), a vector may be necessary, because many keyboard input
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
290 characters are outside the range that will fit in a string. @xref{Key
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
291 Sequence Input}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
292
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293 @node Array Functions
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294 @section Functions that Operate on Arrays
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
296 In this section, we describe the functions that accept all types of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
297 arrays.
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
298
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299 @defun arrayp object
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
300 This function returns @code{t} if @var{object} is an array (i.e., a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
301 vector, a string, a bool-vector or a char-table).
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
302
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305 (arrayp [a])
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
306 @result{} t
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307 (arrayp "asdf")
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
308 @result{} t
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
309 (arrayp (syntax-table)) ;; @r{A char-table.}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
310 @result{} t
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
312 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 @defun aref array index
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316 @cindex array elements
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317 This function returns the @var{index}th element of @var{array}. The
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318 first element is at index zero.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322 (setq primes [2 3 5 7 11 13])
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323 @result{} [2 3 5 7 11 13]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324 (aref primes 4)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325 @result{} 11
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
326 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328 (aref "abcdefg" 1)
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52843
diff changeset
329 @result{} 98 ; @r{@samp{b} is @acronym{ASCII} code 98.}
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
330 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333 See also the function @code{elt}, in @ref{Sequence Functions}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336 @defun aset array index object
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337 This function sets the @var{index}th element of @var{array} to be
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
338 @var{object}. It returns @var{object}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
341 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342 (setq w [foo bar baz])
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 @result{} [foo bar baz]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344 (aset w 0 'fu)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
345 @result{} fu
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
346 w
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347 @result{} [fu bar baz]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
349
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
351 (setq x "asdfasfd")
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352 @result{} "asdfasfd"
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353 (aset x 3 ?Z)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354 @result{} 90
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
355 x
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356 @result{} "asdZasfd"
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 If @var{array} is a string and @var{object} is not a character, a
30983
ce8c496b524d aset change.
Dave Love <fx@gnu.org>
parents: 27189
diff changeset
361 @code{wrong-type-argument} error results. The function converts a
ce8c496b524d aset change.
Dave Love <fx@gnu.org>
parents: 27189
diff changeset
362 unibyte string to multibyte if necessary to insert a character.
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
363 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365 @defun fillarray array object
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
366 This function fills the array @var{array} with @var{object}, so that
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
367 each element of @var{array} is @var{object}. It returns @var{array}.
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
370 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
371 (setq a [a b c d e f g])
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
372 @result{} [a b c d e f g]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373 (fillarray a 0)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374 @result{} [0 0 0 0 0 0 0]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375 a
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
376 @result{} [0 0 0 0 0 0 0]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
377 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
378 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379 (setq s "When in the course")
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
380 @result{} "When in the course"
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381 (fillarray s ?-)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382 @result{} "------------------"
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
383 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
384 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
385
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
386 If @var{array} is a string and @var{object} is not a character, a
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387 @code{wrong-type-argument} error results.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
388 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390 The general sequence functions @code{copy-sequence} and @code{length}
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391 are often useful for objects known to be arrays. @xref{Sequence Functions}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
393 @node Vectors
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
394 @section Vectors
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
395 @cindex vector
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
396
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397 Arrays in Lisp, like arrays in most languages, are blocks of memory
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398 whose elements can be accessed in constant time. A @dfn{vector} is a
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
399 general-purpose array of specified length; its elements can be any Lisp
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
400 objects. (By contrast, a string can hold only characters as elements.)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
401 Vectors in Emacs are used for obarrays (vectors of symbols), and as part
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
402 of keymaps (vectors of commands). They are also used internally as part
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
403 of the representation of a byte-compiled function; if you print such a
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
404 function, you will see a vector in it.
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406 In Emacs Lisp, the indices of the elements of a vector start from zero
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
407 and count up from there.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
408
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
409 Vectors are printed with square brackets surrounding the elements.
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
410 Thus, a vector whose elements are the symbols @code{a}, @code{b} and
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
411 @code{a} is printed as @code{[a b a]}. You can write vectors in the
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
412 same way in Lisp input.
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414 A vector, like a string or a number, is considered a constant for
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 evaluation: the result of evaluating it is the same vector. This does
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416 not evaluate or even examine the elements of the vector.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417 @xref{Self-Evaluating Forms}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
419 Here are examples illustrating these principles:
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423 (setq avector [1 two '(three) "four" [five]])
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424 @result{} [1 two (quote (three)) "four" [five]]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425 (eval avector)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426 @result{} [1 two (quote (three)) "four" [five]]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427 (eq avector (eval avector))
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428 @result{} t
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
430 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
432 @node Vector Functions
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
433 @section Functions for Vectors
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6374
diff changeset
434
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
435 Here are some functions that relate to vectors:
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
436
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
437 @defun vectorp object
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
438 This function returns @code{t} if @var{object} is a vector.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
439
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442 (vectorp [a])
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443 @result{} t
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444 (vectorp "asdf")
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445 @result{} nil
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 @defun vector &rest objects
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 This function creates and returns a vector whose elements are the
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452 arguments, @var{objects}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456 (vector 'foo 23 [bar baz] "rats")
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457 @result{} [foo 23 [bar baz] "rats"]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 (vector)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 @result{} []
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 @defun make-vector length object
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 This function returns a new vector consisting of @var{length} elements,
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 each initialized to @var{object}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 (setq sleepy (make-vector 9 'Z))
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471 @result{} [Z Z Z Z Z Z Z Z Z]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
473 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
474 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476 @defun vconcat &rest sequences
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 @cindex copying vectors
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478 This function returns a new vector containing all the elements of the
54946
dc1950724cd9 Various clarifications.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54479
diff changeset
479 @var{sequences}. The arguments @var{sequences} may be true lists,
dc1950724cd9 Various clarifications.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54479
diff changeset
480 vectors, strings or bool-vectors. If no @var{sequences} are given, an
dc1950724cd9 Various clarifications.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54479
diff changeset
481 empty vector is returned.
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
482
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483 The value is a newly constructed vector that is not @code{eq} to any
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484 existing vector.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
485
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
486 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
487 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
488 (setq a (vconcat '(A B C) '(D E F)))
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
489 @result{} [A B C D E F]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
490 (eq a (vconcat a))
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491 @result{} nil
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
492 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
493 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
494 (vconcat)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
495 @result{} []
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
496 (vconcat [A B C] "aa" '(foo (6 7)))
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
497 @result{} [A B C 97 97 foo (6 7)]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
498 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
499 @end example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
500
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
501 The @code{vconcat} function also allows byte-code function objects as
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
502 arguments. This is a special feature to make it easy to access the entire
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
503 contents of a byte-code function object. @xref{Byte-Code Objects}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
504
52147
b111b96616f0 (Vector Functions): vconcat no longer allows integer args.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
505 In Emacs versions before 21, the @code{vconcat} function allowed
b111b96616f0 (Vector Functions): vconcat no longer allows integer args.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
506 integers as arguments, converting them to strings of digits, but that
b111b96616f0 (Vector Functions): vconcat no longer allows integer args.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
507 feature has been eliminated. The proper way to convert an integer to
b111b96616f0 (Vector Functions): vconcat no longer allows integer args.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
508 a decimal number in this way is with @code{format} (@pxref{Formatting
b111b96616f0 (Vector Functions): vconcat no longer allows integer args.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
509 Strings}) or @code{number-to-string} (@pxref{String Conversion}).
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
510
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
511 For other concatenation functions, see @code{mapconcat} in @ref{Mapping
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
512 Functions}, @code{concat} in @ref{Creating Strings}, and @code{append}
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
513 in @ref{Building Lists}.
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
514 @end defun
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
515
72106
ab0f03398450 (Vector Functions): Delete duplicate xref.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
516 The @code{append} function also provides a way to convert a vector into a
ab0f03398450 (Vector Functions): Delete duplicate xref.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
517 list with the same elements:
6374
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
518
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
519 @example
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
520 @group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
521 (setq avector [1 two (quote (three)) "four" [five]])
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522 @result{} [1 two (quote (three)) "four" [five]]
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
523 (append avector nil)
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524 @result{} (1 two (quote (three)) "four" [five])
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525 @end group
71e61b314fe9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 @end example
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
527
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
528 @node Char-Tables
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
529 @section Char-Tables
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
530 @cindex char-tables
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
531 @cindex extra slots of char-table
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
532
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
533 A char-table is much like a vector, except that it is indexed by
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
534 character codes. Any valid character code, without modifiers, can be
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
535 used as an index in a char-table. You can access a char-table's
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
536 elements with @code{aref} and @code{aset}, as with any array. In
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
537 addition, a char-table can have @dfn{extra slots} to hold additional
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
538 data not associated with particular character codes. Char-tables are
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
539 constants when evaluated.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
540
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
541 @cindex subtype of char-table
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
542 Each char-table has a @dfn{subtype} which is a symbol. The subtype
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
543 has two purposes: to distinguish char-tables meant for different uses,
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
544 and to control the number of extra slots. For example, display tables
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
545 are char-tables with @code{display-table} as the subtype, and syntax
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
546 tables are char-tables with @code{syntax-table} as the subtype. A valid
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
547 subtype must have a @code{char-table-extra-slots} property which is an
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
548 integer between 0 and 10. This integer specifies the number of
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
549 @dfn{extra slots} in the char-table.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
550
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
551 @cindex parent of char-table
38941
bf397d008909 Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 38789
diff changeset
552 A char-table can have a @dfn{parent}, which is another char-table. If
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
553 it does, then whenever the char-table specifies @code{nil} for a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
554 particular character @var{c}, it inherits the value specified in the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
555 parent. In other words, @code{(aref @var{char-table} @var{c})} returns
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
556 the value from the parent of @var{char-table} if @var{char-table} itself
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
557 specifies @code{nil}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
558
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
559 @cindex default value of char-table
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
560 A char-table can also have a @dfn{default value}. If so, then
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
561 @code{(aref @var{char-table} @var{c})} returns the default value
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
562 whenever the char-table does not specify any other non-@code{nil} value.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
563
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
564 @defun make-char-table subtype &optional init
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
565 Return a newly created char-table, with subtype @var{subtype}. Each
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
566 element is initialized to @var{init}, which defaults to @code{nil}. You
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
567 cannot alter the subtype of a char-table after the char-table is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
568 created.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
569
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
570 There is no argument to specify the length of the char-table, because
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
571 all char-tables have room for any valid character code as an index.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
572 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
573
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
574 @defun char-table-p object
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
575 This function returns @code{t} if @var{object} is a char-table,
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
576 otherwise @code{nil}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
577 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
578
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
579 @defun char-table-subtype char-table
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
580 This function returns the subtype symbol of @var{char-table}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
581 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
582
60271
abb79c0e47ac (Arrays): Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 54946
diff changeset
583 @defun set-char-table-default char-table char new-default
abb79c0e47ac (Arrays): Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 54946
diff changeset
584 This function sets the default value of generic character @var{char}
abb79c0e47ac (Arrays): Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 54946
diff changeset
585 in @var{char-table} to @var{new-default}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
586
60271
abb79c0e47ac (Arrays): Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 54946
diff changeset
587 There is no special function to access default values in a char-table.
abb79c0e47ac (Arrays): Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 54946
diff changeset
588 To do that, use @code{char-table-range} (see below).
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
589 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
590
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
591 @defun char-table-parent char-table
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
592 This function returns the parent of @var{char-table}. The parent is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
593 always either @code{nil} or another char-table.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
594 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
595
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
596 @defun set-char-table-parent char-table new-parent
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
597 This function sets the parent of @var{char-table} to @var{new-parent}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
598 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
599
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
600 @defun char-table-extra-slot char-table n
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
601 This function returns the contents of extra slot @var{n} of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
602 @var{char-table}. The number of extra slots in a char-table is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
603 determined by its subtype.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
604 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
605
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
606 @defun set-char-table-extra-slot char-table n value
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
607 This function stores @var{value} in extra slot @var{n} of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
608 @var{char-table}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
609 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
610
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
611 A char-table can specify an element value for a single character code;
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
612 it can also specify a value for an entire character set.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
613
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
614 @defun char-table-range char-table range
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
615 This returns the value specified in @var{char-table} for a range of
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
616 characters @var{range}. Here are the possibilities for @var{range}:
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
617
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
618 @table @asis
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
619 @item @code{nil}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
620 Refers to the default value.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
621
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
622 @item @var{char}
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
623 Refers to the element for character @var{char}
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
624 (supposing @var{char} is a valid character code).
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
625
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
626 @item @var{charset}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
627 Refers to the value specified for the whole character set
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
628 @var{charset} (@pxref{Character Sets}).
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
629
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
630 @item @var{generic-char}
60271
abb79c0e47ac (Arrays): Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 54946
diff changeset
631 A generic character stands for a character set, or a row of a
abb79c0e47ac (Arrays): Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 54946
diff changeset
632 character set; specifying the generic character as argument is
abb79c0e47ac (Arrays): Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 54946
diff changeset
633 equivalent to specifying the character set name. @xref{Splitting
abb79c0e47ac (Arrays): Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 54946
diff changeset
634 Characters}, for a description of generic characters.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
635 @end table
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
636 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
637
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
638 @defun set-char-table-range char-table range value
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
639 This function sets the value in @var{char-table} for a range of
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
640 characters @var{range}. Here are the possibilities for @var{range}:
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
641
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
642 @table @asis
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
643 @item @code{nil}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
644 Refers to the default value.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
645
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
646 @item @code{t}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
647 Refers to the whole range of character codes.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
648
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
649 @item @var{char}
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
650 Refers to the element for character @var{char}
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
651 (supposing @var{char} is a valid character code).
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
652
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
653 @item @var{charset}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
654 Refers to the value specified for the whole character set
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
655 @var{charset} (@pxref{Character Sets}).
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
656
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
657 @item @var{generic-char}
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
658 A generic character stands for a character set; specifying the generic
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
659 character as argument is equivalent to specifying the character set
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
660 name. @xref{Splitting Characters}, for a description of generic characters.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
661 @end table
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
662 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
663
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
664 @defun map-char-table function char-table
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
665 This function calls @var{function} for each element of @var{char-table}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
666 @var{function} is called with two arguments, a key and a value. The key
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
667 is a possible @var{range} argument for @code{char-table-range}---either
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
668 a valid character or a generic character---and the value is
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
669 @code{(char-table-range @var{char-table} @var{key})}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
670
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
671 Overall, the key-value pairs passed to @var{function} describe all the
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
672 values stored in @var{char-table}.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
673
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
674 The return value is always @code{nil}; to make this function useful,
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
675 @var{function} should have side effects. For example,
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
676 here is how to examine each element of the syntax table:
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
677
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
678 @example
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
679 (let (accumulator)
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
680 (map-char-table
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
681 #'(lambda (key value)
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
682 (setq accumulator
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
683 (cons (list key value) accumulator)))
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
684 (syntax-table))
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
685 accumulator)
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
686 @result{}
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
687 ((475008 nil) (474880 nil) (474752 nil) (474624 nil)
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
688 ... (5 (3)) (4 (3)) (3 (3)) (2 (3)) (1 (3)) (0 (3)))
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
689 @end example
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
690 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
691
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
692 @node Bool-Vectors
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
693 @section Bool-vectors
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
694 @cindex Bool-vectors
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
695
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
696 A bool-vector is much like a vector, except that it stores only the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
697 values @code{t} and @code{nil}. If you try to store any non-@code{nil}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
698 value into an element of the bool-vector, the effect is to store
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
699 @code{t} there. As with all arrays, bool-vector indices start from 0,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
700 and the length cannot be changed once the bool-vector is created.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
701 Bool-vectors are constants when evaluated.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
702
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
703 There are two special functions for working with bool-vectors; aside
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
704 from that, you manipulate them with same functions used for other kinds
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
705 of arrays.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
706
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
707 @defun make-bool-vector length initial
38019
59051c56859f Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 30983
diff changeset
708 Return a new bool-vector of @var{length} elements,
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
709 each one initialized to @var{initial}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
710 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
711
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
712 @defun bool-vector-p object
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
713 This returns @code{t} if @var{object} is a bool-vector,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
714 and @code{nil} otherwise.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
715 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
716
38789
72006230a5d8 Add bool-vector example.
Richard M. Stallman <rms@gnu.org>
parents: 38019
diff changeset
717 Here is an example of creating, examining, and updating a
72006230a5d8 Add bool-vector example.
Richard M. Stallman <rms@gnu.org>
parents: 38019
diff changeset
718 bool-vector. Note that the printed form represents up to 8 boolean
72006230a5d8 Add bool-vector example.
Richard M. Stallman <rms@gnu.org>
parents: 38019
diff changeset
719 values as a single character.
72006230a5d8 Add bool-vector example.
Richard M. Stallman <rms@gnu.org>
parents: 38019
diff changeset
720
72006230a5d8 Add bool-vector example.
Richard M. Stallman <rms@gnu.org>
parents: 38019
diff changeset
721 @example
72006230a5d8 Add bool-vector example.
Richard M. Stallman <rms@gnu.org>
parents: 38019
diff changeset
722 (setq bv (make-bool-vector 5 t))
72006230a5d8 Add bool-vector example.
Richard M. Stallman <rms@gnu.org>
parents: 38019
diff changeset
723 @result{} #&5"^_"
72006230a5d8 Add bool-vector example.
Richard M. Stallman <rms@gnu.org>
parents: 38019
diff changeset
724 (aref bv 1)
72006230a5d8 Add bool-vector example.
Richard M. Stallman <rms@gnu.org>
parents: 38019
diff changeset
725 @result{} t
72006230a5d8 Add bool-vector example.
Richard M. Stallman <rms@gnu.org>
parents: 38019
diff changeset
726 (aset bv 3 nil)
72006230a5d8 Add bool-vector example.
Richard M. Stallman <rms@gnu.org>
parents: 38019
diff changeset
727 @result{} nil
72006230a5d8 Add bool-vector example.
Richard M. Stallman <rms@gnu.org>
parents: 38019
diff changeset
728 bv
72006230a5d8 Add bool-vector example.
Richard M. Stallman <rms@gnu.org>
parents: 38019
diff changeset
729 @result{} #&5"^W"
72006230a5d8 Add bool-vector example.
Richard M. Stallman <rms@gnu.org>
parents: 38019
diff changeset
730 @end example
72006230a5d8 Add bool-vector example.
Richard M. Stallman <rms@gnu.org>
parents: 38019
diff changeset
731
72006230a5d8 Add bool-vector example.
Richard M. Stallman <rms@gnu.org>
parents: 38019
diff changeset
732 @noindent
72006230a5d8 Add bool-vector example.
Richard M. Stallman <rms@gnu.org>
parents: 38019
diff changeset
733 These results make sense because the binary codes for control-_ and
72006230a5d8 Add bool-vector example.
Richard M. Stallman <rms@gnu.org>
parents: 38019
diff changeset
734 control-W are 11111 and 10111, respectively.
72006230a5d8 Add bool-vector example.
Richard M. Stallman <rms@gnu.org>
parents: 38019
diff changeset
735
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52147
diff changeset
736 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52147
diff changeset
737 arch-tag: fcf1084a-cd29-4adc-9f16-68586935b386
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52147
diff changeset
738 @end ignore