vectors.texi (6027B)
1 @c -*-texinfo-*- 2 @setfilename ../src/vectors 3 4 @node Vectors, Bytevectors, Ports, Top 5 @comment node-name, next, previous, up 6 7 @chapter Vectors 8 @cindex Vectors 9 10 A vector is an object that contains a sequence of arbitrary klisp 11 objects. A vector has a length that is fixed at creation time, and as 12 many objects, indexed from @code{0} to @code{length-1}. Compared to 13 lists, klisp vectors use less size and have constant access time for 14 any element. 15 16 Vectors may be mutable or immutable. If an attempt is made to mutate 17 an immutable vector, an error is signaled. Two immutable vectors are 18 ``eq?'' iff they are ``equal?''. Two mutable vectors are ``eq?'' if 19 they were created by the same constructor call. Two mutable vectors 20 are ``equal?'' iff they have the same length and have ``equal?'' 21 objects in each position. As is the case for lists, in order to 22 handle possibly cyclic structures, the ``equal?'' algorithm considers 23 vectors as FSMs where it position is a state change. There is only one 24 empty vector (that is, a vector of length 0) and that vector is 25 immutable. The vector type is encapsulated. 26 27 SOURCE NOTE: The report doesn't currently include vectors. They are 28 taken from r7rs scheme. 29 30 @deffn Applicative vector? (vector? . objects) 31 The primitive type predicate for type vector. @code{vector?} 32 returns true iff all the objects in @code{objects} are of type 33 vector. 34 @end deffn 35 36 @deffn Applicative immutable-vector? (immutable-vector? objects) 37 @deffnx Applicative mutable-vector? (mutable-vector? objects) 38 The primitive type predicates for types immutable vector and mutable 39 vector. These return true iff all the objects in @code{objects} are of 40 type immutable vector or mutable vector respectively. 41 @end deffn 42 43 @deffn Applicative make-vector (make-vector k [obj]) 44 Applicative @code{make-vector} constructs and returns a new mutable 45 vector of length @code{k}. If @code{obj} is specified, then all 46 objects in the returned vector are @code{obj}, otherwise the 47 content of the vector is unspecified. 48 @end deffn 49 50 @deffn Applicative vector-length (vector-length vector) 51 Applicative @code{vector-length} returns the length of 52 @code{vector}. 53 @end deffn 54 55 @deffn Applicative vector-ref (vector-ref vector k) 56 Applicative @code{vector-ref} returns the object of @code{vector} at 57 position @code{k}. If @code{k} is out of bounds (i.e. less than 58 @code{0} or greater or equal than @code{(vector-length vector)}) an 59 error is signaled. 60 @end deffn 61 62 @deffn Applicative vector-set! (vector-set! vector k obj) 63 Applicative @code{vector-set!} replaces the object with index @code{k} 64 in @code{vector} with object @code{obj}. If @code{k} is out of 65 bounds, or @code{vector} is immutable, an error is signaled. The 66 result returned by @code{vector-set!} is inert. 67 @end deffn 68 69 @deffn Applicative vector (vector . objs) 70 Applicative @code{vector} contructs and return a new mutable vector 71 composed of the object arguments. 72 @end deffn 73 74 @deffn Applicative vector->list (vector->list vector) 75 @deffnx Applicative list->vector (list->vector objs) 76 These applicatives convert between vectors and lists. The objects 77 returned by these applicatives are always mutable. 78 @end deffn 79 80 @deffn Applicative vector-copy (vector-copy vector) 81 Applicative @code{vector-copy} constructs and returns a new mutable 82 vector with the same length and objects as @code{vector}. 83 @end deffn 84 85 @deffn Applicative vector->bytevector (vector->bytevector vector) 86 @deffnx Applicative bytevector->vector (bytevector->vector bytevector) 87 These applicatives convert between vectors and bytevectors. If a 88 vector containing objects other than exact integers between 0 and 255 89 inclusive are passed to @code{vector->bytevector}, an error is 90 signaled. The objects returned by these applicatives are always 91 mutable. 92 @end deffn 93 94 @deffn Applicative vector->string (vector->string vector) 95 @deffnx Applicative string->vector (string->vector string) 96 These applicatives convert between vectors and strings. If a vector 97 containing objects other than characters is passed to 98 @code{vector->string}, an error is signaled. The objects returned by 99 these applicatives are always mutable. 100 @end deffn 101 102 @deffn Applicative vector-copy! (vector-copy! vector1 vector2) 103 vector2 should have a length greater than or equal to 104 that of vector1. 105 106 Copies the values in vector1 to the corresponding positions in 107 vector2. If vector2 is immutable, an error is signaled. The result 108 returned by @code{vector-copy!} is inert. 109 @end deffn 110 111 @deffn Applicative vector-copy-partial (vector-copy-partial vector k1 k2) 112 Both @code{k1} & @code{k2} should be valid indexes in 113 @code{vector}. Also it should be the case that @code{k1 <= k2}. 114 115 Applicative @code{vector-copy-partial} constructs and returns a new 116 mutable vector with length @code{k2 - k1}, with the objects from 117 @code{vector}, starting at index @code{k1} (inclusive) and ending at 118 index @code{k2} (exclusive). 119 @end deffn 120 121 @deffn Applicative vector-copy-partial! (vector-copy-partial! vector1 k1 k2 vector2 k3) 122 Both @code{k1} & @code{k2-1} should be valid indexes in 123 @code{vector1}. Also it should be the case that @code{k1 <= k2}. 124 Both @code{k3} & @code{k3 + (k2-k1) - 1} should be valid indexes in 125 @code{vector2}. 126 127 Applicative @code{vector-copy-partial!} copies objects k1 (inclusive) 128 through k2 (exclusive) from @code{vector1} to the @code{k2-k1} 129 positions in @code{vector2} starting at @code{k3}. If @code{vector2} 130 is an immutable vector, an error is signaled. The result returned by 131 @code{vector-copy-partial!} is inert. 132 @end deffn 133 134 @deffn Applicative vector-fill! (vector-fill! vector obj) 135 Applicative @code{vector-fill!} replaces all the objects in 136 @code{vector} with object @code{obj}. If @code{vector} is an 137 immutable vector, an error is signaled. The result 138 returned by @code{vector-fill!} is inert. 139 @end deffn 140 141 @deffn Applicative vector->immutable-vector (vector->immutable-vector vector) 142 Applicative @code{vector->immutable-vector} constructs and returns a 143 new immutable vector with the same length and objects as 144 @code{vector}. 145 @end deffn