r7rs-small-texinfo

R7RS-small Scheme converted to Texinfo.
git clone https://kaka.farm/~git/r7rs-small-texinfo
Log | Files | Refs | README | LICENSE

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