The COPY DQF

Having seen that link entries can be updated you may now be wondering if data entries can as well. The answer is that they can using the COPY DQF. The DQF is used as follows:-

 
' _         copy         _my_data,                        '
'                        source,                          '
'                        num_words;                       '

where:-

_my_data

is previously defined data entry.

source

is the source of the data. It can be any type of parameter. If this parameter is omitted, the source is taken to be the word in the n-tuple that precedes the current entry.

num_words

is the number of words to be copied. If this parameter is omitted, 1 is assumed.

COPY simply copies words from the specified source; it does not know the type of this data, so cannot convert from integer to floating point; it is your responsibility not to end up with integers in the n-tuple. However literal parameters are converted when the command is compiled so, for example:-

 
' _         copy         _my_data, 1;                     '

will store 1.0 in _my_data. As all DQF's have to return values, COPY dutifully returns 1.0, which you unlikely to want; its the side effect of updating its first parameter that is of interest. Note the COPY won't operate if any of its parameters are undefined, and this includes its first parameter.

One use of COPY is as a way of storing alternative results in an entry depending on the result of some test. Suppose two entries _my_data_1 and _my_data_2 hold alternative results and _my_test is used to decide which is to be store in result. This can be done as follows:-

 
' result        equals       _my_data_1;                      '
' _             jump_true    +2., _my_test;                   '
' _             copy         result, _my_data2;               '

It can also be used to form simple counters, exploiting the fact that the EQUALS DQF sums its parameters if more than one:-

 
' counter       equals       0.                               '
#.
#.
#.
' _             equals       counter, 1.;                     '
' _             copy         counter;                         '

The first line clears the counter to zero. Later, counter plus 1. are summed and stored in an unnamed entry. The following COPY has only a single parameter so takes as its source the previous word and copies it into counter.