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]  

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)  
    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])  
    3 lisp> (copyvectortofrom b a)  
    [[1 2 3]]  
    4 lisp> (eq (getv a 0) (getv b 0))  

(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))  

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.