PUT inputVector positionsVector resultVector

The PUT command copies values from its input vector and inserts them into its result vector at locations specified by its positions vector. The elements of the input vector and those of the positions vector are associated by their order. That is, the first element of the input vector is associated with the first element of the positions vector, the second with the second, etc. Therefore, the first element of the input vector is put into the result vector at the position that is specified by the first element of the positions vector.

The changes are made in place to the result vector. If there was already an element at a specified position in the result vector, that element is replaced. If there was no element at a specified position (either the resultVector is empty or too short), the result vector will be extended as necessary to contain the input element at the specified location. In that case, any intervening positions of the result vector will contain NaN.

Study the examples at the right to understand PUT's behavior more clearly.

The PUT command together with the TAKE command allow vectors to be treated similarly to the indexable arrays of other computer languages.

Note that the input vector and the output vector may be the same vector. For example, suppose you wanted to swap the first two numbers and you tried this:

COPY (10 20 30 40) a
PUT a (2 1) a  'Same vector for input and output

you will get this result:

a: (10.0 20.0 30.0 40.0)
a: (20.0 10.0 30.0 40.0)

The PUT command detects that the output vector and the input vector are the same and will make a temporary copy of the input vector to avoid the vector's self-destruction that would occur by writing to itself as the computation progresses.

The following examples show the results of various behaviors of the PUT command.

COPY (1 2 3 4 5 6 7) result
PUT (11 12 13) (1 3 5) result
PRINT result

The above program produces this output:

result: (11.0 2.0 12.0 4.0 13.0 6.0 7.0)

In a computer language like Java or C, the above PUT command is equivalent to the following three statements:

result[1] = 11;
result[3] = 12;
result[5] = 13;

Given the same result vector, but a shorter input vector,

PUT (11 12) (1 3 5) result
result: (11.0 2.0 12.0 4.0 5.0 6.0 7.0)

we get only two numbers transferred even though the positions vector is longer, because that is all that is available from the input vector.

With an input vector longer than the positions vector, like this,

PUT (11 12 13) (1 3) result

we get this result:

result: (11.0 2.0 12.0 4.0 5.0 6.0 7.0)

This is the same result as before, because now, the positions vector has only two elements, so that is all that will be copied over to the result vector.

In this next example, the positions vector contains an index, 10, that is beyond the current length of the result vector.

PUT (11 12 13 14 15) (1 3 10) result

with this output:

result: (11.0 2.0 12.0 4.0 5.0 6.0 7.0 NaN NaN 13.0)

Here, the result vector was extended to allow insertion of the third input value at the tenth position, which didn't previously exist. The intervening positions of the result vector were filled with NaN.