UNPACK (VECTOR, MASK, FIELD)

9.3.163 UNPACK (VECTOR, MASK, FIELD)

Description:	Takes elements from a rank-one array and unpacks them into another (possibly larger) array under the control of a mask.
Class:	Transformational function; Generic
Arguments:	VECTOR	Must be a rank-one array (of any data type). Its size must be at least t, where t is the number of true elements in MASK.
	MASK	Must be a logical array. It determines where elements of VECTOR are placed when they are unpacked.
	FIELD	Must be of the same type and type parameters as VECTOR and conformable with MASK. Elements in FIELD are inserted into the result array when the corresponding MASK element has the value false.
Results:	The result is an array with the same shape as MASK, and the same type and type parameters as VECTOR. Elements in the result array are filled in array element order. If element i of MASK is true, the corresponding element of the result is filled by the next element in VECTOR. Otherwise, it is filled by FIELD (if FIELD is scalar) or the ith element of FIELD (if FIELD is an array).

Examples

N is the array

  [ 0  0  1 ]
  [ 1  0  1 ]
  [ 1  0  0 ],

P is the array (2, 3, 4, 5), and Q is the array

  [ T  F  F ]
  [ F  T  F ]
  [ T  T  F ].

UNPACK (P, MASK=Q, FIELD=N) produces the result

  [ 2  0  1 ]
  [ 1  4  1 ]
  [ 3  5  0 ].

UNPACK (P, MASK=Q, FIELD=1) produces the result

  [ 2  1  1 ]
  [ 1  4  1 ]
  [ 3  5  1 ].