ArrayTools[BlockCopy] - copy a block of several segments of elements from one Matrix, Vector, or Array to another
|
Calling Sequence
|
|
BlockCopy(A,offsetA,skipA,segsizeA,numsegsA,B,offsetB,skipB,segsizeB,numsegsB)
|
|
Parameters
|
|
A
|
-
|
source; rectangular storage Matrix, Vector, or Array of any data type and ordering
|
offsetA
|
-
|
(optional); offset for source
|
skipA
|
-
|
increment for source; the number of elements between the start of consecutive segments
|
segsizeA
|
-
|
(optional); segment size for source; the number of elements in each segment. Must not be larger than skipA. Can be specified only if offsetA is specified
|
numsegsA
|
-
|
(optional); number of segments to copy from source. Can only be specified if segsizeA is specified
|
B
|
-
|
target; rectangular storage Matrix, Vector, or Array of matching data type and any ordering
|
offsetB
|
-
|
(optional); offset for target
|
skipB
|
-
|
increment for target; the number of elements between the start of consecutive segments
|
segsizeB
|
-
|
(optional); segment size for target, if different from segsizeA. Must not be larger than skipB. Can be specified only if offsetB is specified
|
numsegsB
|
-
|
(optional); number of segments to write data to when copying into target. Can only be specified if segsizeB is specified
|
|
|
|
|
Description
|
|
•
|
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](..).
|
|
|
Examples
|
|
>
|
|
Copy the upper-right 3x2 block of a Fortran order Matrix into another Matrix:
>
|
|
| (1) |
>
|
|
>
|
|
>
|
|
| (2) |
Use the offset parameter to copy the block into the lower left of another Fortran order Matrix:
>
|
|
>
|
|
>
|
|
| (3) |
Copy the same block, but reshape it into a 6x1 column Vector:
>
|
|
>
|
|
>
|
|
| (4) |
The original example, but with a C order Matrix instead. Note the different parameter values:
>
|
|
| (5) |
>
|
|
>
|
|
>
|
|
| (6) |
BlockCopy can be used to create a Matrix from several sub-matrices.
>
|
|
| (7) |
>
|
|
| (8) |
>
|
|
| (9) |
>
|
|
>
|
|
>
|
|
>
|
|
>
|
|
| (10) |
Extract every second row of a C order Matrix, and concatenate them into a row vector. Here, since you are skipping every second row, the skipA parameter is not equal to the number of columns:
>
|
|
| (11) |
>
|
|
| (12) |
>
|
|
>
|
|
| (13) |
|
|