copy shelf-type? shelf-name to shelf-name

Used to copy the entire contents of one shelf to another. This action replaces the contents of the destination shelf with the contents of the source shelf.

The shelf type is an optional herald that can be omitted. The first shelf name refers to the shelf being copied; the second refers to the destination shelf.

Both the source and destination shelves must be of the same type (switch, counter or stream). Because the destination shelf will become the same size as the source shelf, it must have either a declared size of variable or be the same size as the source shelf. If the destination shelf was declared variable with a maximum size, the maximum size must be equal to or greater than the current size of the source shelf.

When stream shelves are copied, all streams on the source shelf must be either closed and attached to buffers or unattached. All open streams on the destination shelf will automatically be closed before the copy action takes place.

This code fragment illustrates how copy can be used to copy the contents of one shelf into another.

This example copies all the items of the counter 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 "reference-counts" has the same value and key as its corresponding item in "saved-reference-counts".

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