PACK(ARRAY, MASK, VECTOR)

Purpose

Takes some or all elements from an array and packs them into a one-dimensional array, under the control of a mask.

Class

Transformational function

Argument type and attributes

ARRAY: is the source array, whose elements become part of the result. It can have any data type.
MASK: must be of type logical and must be conformable with ARRAY. It determines which elements are taken from the source array. If it is a scalar, its value applies to all elements in ARRAY.
VECTOR (optional): is a padding array whose elements are used to fill out the result if there are not enough elements selected by the mask. It is a one-dimensional array that has the same data type and type parameters as ARRAY and at least as many elements as there are true values in MASK. If MASK is a scalar with a value of .TRUE., VECTOR must have at least as many elements as there are array elements in ARRAY.

Result value

The result is always a one-dimensional array with the same data type and type parameters as ARRAY.

The size of the result depends on the optional arguments:

If VECTOR is specified, the size of the resultant array equals the size of VECTOR.
Otherwise, it equals the number of true array elements in MASK, or the number of elements in ARRAY if MASK is a scalar with a value of .TRUE..

The array elements in ARRAY are taken in array element order to form the result. If the corresponding array element in MASK is .TRUE., the element from ARRAY is placed at the end of the result.

If any elements remain empty in the result (because VECTOR is present, and has more elements than there are .TRUE. values in mask), the remaining elements in the result are set to the corresponding values from VECTOR.

Examples

! A is the array  |  0  7  0 |
!                 |  1  0  3 |
!                 |  4  0  0 |

! Take only the non-zero elements of this sparse array.
! If there are less than six, fill in -1 for the rest.
RES = PACK(A, MASK= A .NE. 0, VECTOR=(/-1,-1,-1,-1,-1,-1/)
! The result is (/ 1, 4, 7, 3, -1, -1 /).

! Elements 1, 4, 7, and 3 are taken in order from A
! because the value of MASK is true only for these
! elements. The -1s are added to the result from VECTOR
! because the length (6) of VECTOR exceeds the number
! of .TRUE. values (4) in MASK.