vectors.texinfo (6325B)
1 @node Vectors 2 @section Vectors 3 4 Vectors are heterogeneous structures whose elements are indexed by 5 integers. A vector typically occupies less space than a list of the 6 same length, and the average time needed to access a randomly chosen 7 element is typically less for the vector than for the list. 8 9 The @define{length} of a vector is the number of elements that it contains. 10 This number is a non-negative integer that is fixed when the vector is 11 created. The @define{valid indexes} of a vector are the exact non-negative 12 integers less than the length of the vector. The first element in a 13 vector is indexed by zero, and the last element is indexed by one less 14 than the length of the vector. 15 16 Vectors are written using the notation @code{#(}@var{obj} @dots{}@code{)}. 17 For example, a vector of length 3 containing the number zero in element 18 0, the list @code{(2 2 2 2)} in element 1, and the string @code{"Anna"} 19 in element 2 can be written as follows: 20 21 @lisp 22 #(0 (2 2 2 2) "Anna") 23 @end lisp 24 25 Vector constants are self-evaluating, so they do not need to be quoted 26 in programs. 27 28 @deffn procedure vector? obj 29 30 Returns @code{#t} if @var{obj} is a vector; otherwise returns 31 @code{#f}. 32 33 @end deffn 34 35 @deffn procedure make-vector k 36 @deffnx procedure make-vector k fill 37 38 Returns a newly allocated vector of @var{k} elements. If a second 39 argument is given, then each element is initialized to @var{fill}. 40 Otherwise the initial contents of each element is unspecified. 41 42 @end deffn 43 44 @deffn procedure vector obj@dots{} 45 46 Returns a newly allocated vector whose elements contain the given 47 arguments. It is analogous to @code{list}. 48 49 @lisp 50 (vector 'a 'b 'c) @result{} #(a b c) 51 @end lisp 52 @end deffn 53 54 @deffn procedure vector-length vector 55 56 Returns the number of elements in 57 @var{vector} as an exact integer. 58 @end deffn 59 60 @deffn procedure vector-ref vector k 61 62 It is an error if @var{k} is not a valid index of @var{vector}. 63 64 The @code{vector-ref} procedure returns the contents of element @var{k} 65 of @var{vector}. 66 67 @lisp 68 (vector-ref '#(1 1 2 3 5 8 13 21) 69 5) 70 @result{} 8 71 (vector-ref '#(1 1 2 3 5 8 13 21) 72 (exact 73 (round (* 2 (acos -1))))) 74 @result{} 13 75 @end lisp 76 @end deffn 77 78 @deffn procedure vector-set! vector k obj 79 80 It is an error if @var{k} is not a valid index of @var{vector}. 81 82 The @code{vector-set!} procedure stores @var{obj} in element @var{k} of 83 @var{vector}. 84 85 @lisp 86 (let ((vec (vector 0 '(2 2 2 2) "Anna"))) 87 (vector-set! vec 1 '("Sue" "Sue")) 88 vec) 89 @result{} #(0 ("Sue" "Sue") "Anna") 90 91 (vector-set! '#(0 1 2) 1 "doe") @result{} @r{error} ; constant vector 92 @end lisp 93 94 @end deffn 95 96 @deffn procedure vector->list vector 97 @deffnx procedure vector->list vector start 98 @deffnx procedure vector->list vector start end 99 @deffnx procedure list->vector list 100 101 The @code{vector->list} procedure returns a newly allocated list of the 102 objects contained in the elements of @var{vector} between @var{start} 103 and @var{end}. The @code{list->vector} procedure returns a newly 104 created vector initialized to the elements of the list @var{list}. 105 106 In both procedures, order is preserved. 107 108 @lisp 109 (vector->list '#(dah dah didah)) @result{} (dah dah didah) 110 (vector->list '#(dah dah didah) 1 2) @result{} (dah) 111 (list->vector '(dididit dah)) @result{} #(dididit dah) 112 @end lisp 113 114 @end deffn 115 116 @deffn procedure vector->string vector 117 @deffnx procedure vector->string vector start 118 @deffnx procedure vector->string vector start end 119 @deffnx procedure string->vector string 120 @deffnx procedure string->vector string start 121 @deffnx procedure string->vector string start end 122 123 It is an error if any element of @var{vector} between @var{start} 124 and @var{end} is not a character. 125 126 The @code{vector->string} procedure returns a newly allocated string of 127 the objects contained in the elements of @var{vector} between 128 @var{start} and @var{end}. The @code{string->vector} procedure returns 129 a newly created vector initialized to the elements of the string 130 @var{string} between @var{start} and @var{end}. 131 132 In both procedures, order is preserved. 133 134 @lisp 135 (string->vector "ABC") @result{} #(#\A #\B #\C) 136 (vector->string #(#\1 #\2 #\3) @result{} "123" 137 @end lisp 138 139 @end deffn 140 141 @deffn procedure vector-copy vector 142 @deffnx procedure vector-copy vector start 143 @deffnx procedure vector-copy vector start end 144 145 Returns a newly allocated copy of the elements of the given 146 @var{vector} between @var{start} and @var{end}. The elements of the new 147 vector are the same (in the sense of @code{eqv?}) as the elements of 148 the old. 149 150 @lisp 151 (define a #(1 8 2 8)) ; a may be immutable 152 (define b (vector-copy a)) 153 (vector-set! b 0 3) ; b is mutable 154 b @result{} #(3 8 2 8) 155 (define c (vector-copy b 1 3)) 156 c @result{} #(8 2) 157 @end lisp 158 @end deffn 159 160 @deffn procedure vector-copy! to at from 161 @deffnx procedure vector-copy! to at from start 162 @deffnx procedure vector-copy! to at from start end 163 164 It is an error if @var{at} is less than zero or greater than the 165 length of @var{to}. It is also an error if 166 @code{(- (vector-length }@var{to}@code{) }@var{at}@code{)} 167 is less than @code{(- }@var{end} @var{start}@code{)}. 168 169 Copies the elements of vector @var{from} between @var{start} and 170 @var{end} to vector @var{to}, starting at @var{at}. The order in which 171 elements are copied is unspecified, except that if the source and 172 destination overlap, copying takes place as if the source is first 173 copied into a temporary vector and then into the destination. This can 174 be achieved without allocating storage by making sure to copy in the 175 correct direction in such circumstances. 176 177 @lisp 178 (define a (vector 1 2 3 4 5)) 179 (define b (vector 10 20 30 40 50)) 180 (vector-copy! b 1 a 0 2) 181 b @result{} #(10 1 2 40 50) 182 @end lisp 183 184 @end deffn 185 186 @deffn procedure vector-append vector@dots{} 187 188 Returns a newly allocated vector whose elements are the concatenation 189 of the elements of the given @var{vector}s. 190 191 @lisp 192 (vector-append #(a b c) #(d e f)) @result{} #(a b c d e f) 193 @end lisp 194 195 @end deffn 196 197 @deffn procedure vector-fill! vector fill 198 @deffnx procedure vector-fill! vector fill start 199 @deffnx procedure vector-fill! vector fill start end 200 201 The @code{vector-fill!} procedure stores @var{fill} in the elements of 202 @var{vector} between @var{start} and @var{end}. 203 204 @lisp 205 (define a (vector 1 2 3 4 5)) 206 (vector-fill! a 'smash 2 4) 207 a @result{} #(1 2 smash smash 5) 208 @end lisp 209 210 @end deffn