copy, copy-clear

action

Syntax
copy source to destination
or
copy-clear source to destination
    


Purpose

You can use copy to copy the entire contents of one shelf to another. The contents of destination are removed and replaced with a copy of the contents of source.

You can use copy-clear to copy the entire contents of one shelf to another. The contents of source are moved to destination, thereby leaving source empty.

Both source and destination must be of the same data type. In the case of shelves of a record type, you may also copy a shelf of an extended record type to a shelf of the type it extends.

Because destination will become the same size as source, it must be either variable size or the same size as source. If destination was declared variable with a maximum size, the maximum size must be equal to or greater than the current size of source.

For copy-clear, source must be of variable size, since fixed-sized shelves cannot be cleared.

When stream shelves are copied using copy, all streams on source must either be unattached or attached to buffers and closed. When you use copy-clear, however, streams on source may be attached and opened and will remain attached an opened on destination.

All opened streams on destination will automatically be discarded before the copy action takes place.

Example

This example copies all the items of the integer shelf reference-counts to saved-reference-counts. After the copy, saved-reference-counts has the same number of items as reference-counts, and each item in saved-reference-counts has the same value and key as its corresponding item in reference-counts.

  global integer reference-counts
  
  process
     local integer saved-reference-counts
  
     copy reference-counts to saved-reference-counts

copy does not copy the values of a shelf of records but the references to these records. After the copy both shelves reference the same set of records.

Related Syntax
Related Concepts