20.1 Vectors
A vector is a structured entity in which random elements may be accessed with an
integer index. A vector has a single dimension. Its maximum size is determined by the
implementation and available space. A vector is denoted by enclosing its elements within square
brackets.
[10 TEN]
[COLORS (RED BLUE)]
Built-in Vector Creation and Copying Functions
(mkvect UPLIM:integer): vector expr
Defines and allocates space for a vector with (add1 UPLIM) elements
accessed as 0 ... UPLIM. Each element is initialized to nil. If UPLIM is -1,
an empty vector is returned. An error occurs if UPLIM is less than -1 or if
the amount of available memory is insufficient for a vector of this size.
⋆⋆⋆⋆⋆ A vector of size UPLIM cannot be allocated
(make-vector UPLIM:integer INITVAL:any): vector expr
Similar to mkvect, except that each element is initialized to INITVAL. Note
the difference between this function and make-string, (see the section on
creating and copying strings in Chapter 6). This function creates a vector
of (add1 UPLIM) elements where make-string creates a string of UPLIM
characters.
The vector created by this function will contain (add1 UPLIM) references to INTVAL as
opposed to creating a copy of UPLIM for each entry.
1 lisp> (setq array (make-vector 1 (make-vector 1 0)))
[[0 0] [0 0]]
2 lisp> (vector-store (vector-fetch array 0) 0 1)
1
3 lisp> array
[[1 0] [1 0]]
(vector [ARGS:any]): vector nexpr
Create vector of elements from the list ARGS. The size of the vector will
be equal to the number of elements in the list ARGS. Each element of the
vector is initialized to the corresponding element from ARGS
(copyvectortofrom NEW:vector OLD:vector):NEW:vector expr
The elements of NEW are set to the corresponding elements of OLD The
elements are not copied.
1 lisp> (setq a [[1 2 3]])
[[1 2 3]]
2 lisp> (setq b [0])
[0]
3 lisp> (copyvectortofrom b a)
[[1 2 3]]
4 lisp> (eq (getv a 0) (getv b 0))
t
(copyvector V:vector): vector expr
Create a new vector, with the elements initalized from the corresponding
elements of V. The elements of V are not copied.
1 lisp> (setq a "A STRING")
"A STRING"
2 lisp> (setq b (vector a))
["A STRING"]
3 lisp> (setq c (copyvector b))
["A STRING"]
4 lisp> (eq (getv b 0) (getv c 0))
t
20.1.1 About the Basic Operations on Vectors
The functionality provided here overlaps what is provided in some other ways. The functions
provided here have well-chosen names and definitions, they provide the option of
generating efficient code, and they are consistent with the esthetic preferences of our
community.
20.1.2 The Operations
This section documents functions in the library module slow-vectors . There is another library
module called fast-vectors. The fast-vectors module provides alternate definitions for these
functions. When the switch fast-vectors is non-nil the compiler will use these alternate
definitions to produce effiecient code. However, there will not be any verification that arguments
are of correct type (in addition, it is assumed that numeric arguments are within a proper range).
If invalid arguments are used, then at best your code will not generate correct results, you may
actually damage the PSL system. There are two side effects to loading fast-vectors.
The slow-vectors module will be loaded and the switch fast-vectors will be set to
t.
(vector-fetch V:vector I:integer): any expr
Accesses an element of a PSL vector. Vector indexes start with 0. The thing
stored in that position of the vector is returned.
(vector-store V:vector I:integer X:any): None Returned expr
Stores into a PSL vector. Vector indexes start with 0.
(vector-size V:vector): integer expr
Returns the number of elements in a PSL vector. Since indexes start with
index 0, the size is one larger than the greatest legal index. See also just
below.
(vector-upper-bound V:vector): integer expr
Returns the greatest legal index for accessing or storing into a PSL vector.
See also just above.
(vector-empty? V:vector): boolean expr
True if the vector has no elements (its size is 0), otherwise NIL.
20.1.3 Built-in Operations on Vectors
These predate the fast-vectors (f-vector) and slow-vectors (s-vector) library modules.
(getv V:vector INDEX:integer): any expr
Returns the value stored at position INDEX of the vector V. The type
mismatch error may occur. An error occurs if the INDEX does not lie within
0 ... (upbv V) inclusive:
⋆⋆⋆⋆⋆ INDEX subscript is out of range
(putv V:vector INDEX:integer VALUE:any): any expr
Stores VALUE in the vector V at position INDEX, VALUE is returned.
A type mismatch error will occur if V is not a vector. If INDEX is either
negative or greater than (upbv V) then an error occurs.
⋆⋆⋆⋆⋆ Subscript ‘INDEX' in PutV is out of range
(upbv U:any): nil, integer expr
Returns the upper limit of U if U is a vector, or nil if it is not.