The BlockCopy command copies a block of data from an existing Matrix, Vector, or Array (source) to another Matrix, Vector, or Array (target). The data types of the source and target must match, or an error results. In addition, the source and target must both have rectangular (dense) storage.

In contrast to ArrayTools[Copy], which copies a single segment of data from the source to the target, BlockCopy copies multiple equally spaced equal-sized segments of elements from the source to the target.  Such segments must be groups of contiguous elements when the underlying one-dimensional ordering of the source rtable is considered.  The result depends only upon the internal ordering of the elements in the input rtable, and is independent of the shape of the source or target rtables. Consequently, this routine requires knowledge of the storage structure of multi-dimensional rectangular rtables under different data orderings (C_order and Fortran_order).  For a description of storage under these orderings, see Fortran_order.

With the source and target segment sizes set to 1, BlockCopy behaves in the same manner as ArrayTools[Copy].  The command ArrayTools[Copy](num,A,offsetA,skipA,B,offsetB,skipB) performs the same data movements as the command ArrayTools[BlockCopy](A,offsetA,skipA,1,num,B,offsetB,skipB,1,num).

The parameters offsetA, skipA, segsizeA, numsegsA, offsetB, skipB, segsizeB, and numsegsB provide a mechanism for specifying the size, shape, and location of the source and destination blocks.  The data copied from the source is a block of numsegsA segments of segsizeA elements.  The first segment starts at position offsetA+1, and each subsequent segment begins skipA elements after the previous one.  These segsizeA*numsegsA elements are copied into numsegsB segments of segsizeB elements in the target.  The first target segment starts at position offsetB+1, and each subsequent segment begins skipA elements after the previous one.

The default values of the optional parameters are described as follows:

offsetA and offsetB are  (start at the very beginning)

segsizeA and numsegsA are  (copy one segment of one element)

segsizeB is equal to  (copy each source segment into a target segment of equal size)

numsegsB is equal to  (copy the source block into a target block containing an equal number of elements; numsegsB will be exactly numsegsA if segsizeB is also unspecified.)

The skipA and skipB parameters must be specified.  When copying a submatrix of elements from a 2-dimensional Array or Matrix, skipA and skipB are usually set to the number of rows (for Fortran order rtables) or the number of columns (for C order rtables) of the source and target rtables, respectively.  Making the source and target increments equal to the number of rows (or number of columns, for C order rtables) tells BlockCopy to copy using the same offset in each column (or row), thereby copying a physical rectangular submatrix of elements.

As an example, copying the upper-right  by  block of an  by  C order Matrix A (where  and ) corresponds to accessing the elements  of the underlying rtable data structure (for  and ).  The source offset would be , since the first  elements are skipped.  The source increment would be  (the number of columns in the input rtable), since each segment begins exactly one row, or  elements, after the previous one.  The segment size and number of segments would be  and , respectively.  To copy this into a  by  C order Matrix B, only skipB would need to be computed, since the default values for the other parameters would copy a block of identical size and shape into B.  The command to accomplish this would then be BlockCopy(A,m-q,m,q,p,B,q) (where m, n, p, and q are fixed values corresponding to the problem.)

In contrast, the same operation for an  by  Fortran order rtable must be specified differently. The source offset will now be , since all the values in the first m-q columns are skipped. The source increment will be  (the number of rows) and the segment size and number of segments become reversed, giving us  segments of  elements instead of  segments of  elements.  If the destination is a  by  Fortran order Matrix, the command to accomplish this is BlockCopy(A,n*(m-q),n,p,q,B,p).

This function is part of the ArrayTools package, so it can be used in the short form BlockCopy(..) only after executing the command with(ArrayTools).  However, it can always be accessed through the long form of the command by using ArrayTools[BlockCopy](..).