annotate doc/lispref/sequences.texi @ 111109:ee0f7585b521

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