PUTI

Member Of Menu: 
List
Array
Argument Types: 
Any
Real
Complex
List
Symbol
Array
Result Type(s): 
Real
List
Symbol
Array
Invertible: 
No
Valid In Expression: 
No
Stack Diagram: 
List1 Real2 Item3 → List4 Real5
List1 List2 Item3 → List4 List5
Array1 Real2 Item3 → Array4 Real5
Array1 List2 Item3 → Array4 List5
Symbol1 Real2 Item3 → Symbol1 Real4
Symbol1 List2 Item3 → Symbol1 List4

This operation is used to replace an item in a list, vector or matrix at a particular index. It can either modify a list, vector or matrix on the stack or a one stored in memory, referenced by a symbol name. If provided a list, the real number is used as an index into the list to find the item to replace and the new item to put at that location is found at the top of the stack. The modified list is pushed onto the stack. Also, the index is incremented and also pushed onto the stack. The intention is to then push a new item onto the stack for the next item on the list and execute PUTI again. This makes it easy to quickly modify all items on the list, one after the other. For a list, the index can also be a list with a single real value.

Similarly, the operation can modify a vector. The index for a vector can be a real number or a list with a single real number. The item to put in the vector must be a real or complex value. If the item to put in the vector is complex, the vector itself must be complex.

Finally, the operation can modify a matrix. The index for a matrix must be a list with two real values representing the row number of column number of the item. The item to put in the matrix must be a real or complex value. If the item to put in the matrix is complex, the matrix itself must be complex. When incrementing the index on a matrix, the operation will visit each value in a row, column by column before proceeding to the next row.

If provided a symbol, the value of that symbol is retrieved which should be a list, vector or matrix. The item at that index is replaced with the new item and then stored as the value of that symbol. The symbol is left on the stack and the index is incremented so it points to the next index. Again, this allows all items in the list to be quickly modified, one after the other.

When incrementing the index, if the next value is beyond the end of the list, vector or matrix, the index wraps to the first item. Also, this operation sets the 46th flag as described in the Working With Programs guide if the index wrapped. Otherwise, it clears the flag. Testing this flag can be useful in a program in order to loop over all items in the list, vector or matrix.