HELP
An object that collects data and outputs an
array.

USE
Use Collector to create a one-dimensional
array from scalar input data, or to create an
output array from collected input arrays.  If
the input arrays have "n" dimensions, the
collector can either output an array of n+1
dimensions, or it can output a
one-dimensional array (with the input data
"flattened").  When all data has been
collected, activate the XEQ pin to output the
resulting array.

LOCATION
Data ==> Collector

OPEN VIEW PARAMETERS

* Output Shape - Choose one of two
selections:

* n+1 Dim Array - The input signals (arrays
of n dimensions) are collected and output as
an array of n+1 dimensions.

* 1 Dim Array - The input signals, regardless
of shape, are "flattened" by the collector
and output as an Array 1D.
(For scalar input data, the output shape will
be "Array 1D" regardless of the selection.)

OBJECT MENU

* Clear - Clears the contents of the
Collector.

* Clear at PreRun - Clears the contents of
the Collector at PreRun.  Default is on
(checked).

* Clear at Activate - Clears the contents of
the Collector at activate.  Default is on
(checked).

NOTES
Because XEQ is required on the Collector you
cannot add another trigger pin or delete it.

The Collector continues to collect the
input data until the XEQ pin is triggered.

The Collector has two inputs; one for the
data coming in (any shape and type); the
other tells the device when to execute.  The
device accepts multiple input data hits on
the first data input pin, and collects the
data until the XEQ pin is hit.  Then the
device copies the full set of data to its
output pin and propagates its output.  The
output data pin is never propagated until the
XEQ pin is hit.  Once the data propagates,
the Collector clears its internal buffer and
again starts collecting data.  The type of
the output signal is determined by the type
of the first data container coming in after
each XEQ or Clear.  All subsequent containers
are coerced to the type of the first one.  If
coercion fails, an error is reported.

The shape of the output signal depends on
the Output Shape selection:

* n+1 Dim Array operation - If you select n+1
Dim Array for the Output Shape, the Collector
will collect the data coming into its Data
pin, and will output an array of one
dimension higher than the number of
dimensions of the input data.  Each input
signal must be the same size and shape as the
first input signal, until the XEQ pin is
triggered.  No mapping information is copied
-- the output signal is not mapped.

For example, if the first input data is a
Real 1D array, 10 long, each subsequent input
signal must be a 1D array, 10 long, of a type
that can be coerced into Real, until the XEQ
pin is triggered.  The output signal will be
a Real 2D array with 10 columns and n rows,
where "n" is the number of times data was
sent to the Data input pin before XEQ was
triggered.

* 1 Dim Array operation - If you select 1 Dim
Array for the Output Shape, the Collector
collects the data coming into its Data pin
and outputs an Array 1D, regardless of the
shape of the input data.  Scalar or Array 1D
data is appended to the end;
multi-dimensional arrays are flattened into
an Array 1D and then appended.

For example, if the data in is a scalar
Real value 1.2, then a scalar Int32 value 34,
then XEQ is hit, it will output a Real Array
1D, two long, with the values [1.2 34.0].
Then, if it is hit with several Complex data
containers, it will output a Complex Array
1D.

Note that for scalar inputs of any type,
the Collector will generate the same output
signal regardless of the Output Shape
selection.

Since Waveform and Spectrum signals do not
support more than one dimension, they are not
allowed as inputs when the Collector is
operating in the n+1 Dim Array mode.  To
collect Waveform or Spectrum data into a 2D
array, unbuild the data first and then
collect it into a 2D array.  Note that the
mapping information will be lost.

Since Record and Coord containers only
support up to 1D arrays, only scalar Record
or Coord containers are allowed as inputs
when the Collector is operating in the n+1
Dim Array mode.

Enum inputs are converted to type Text
before being placed into an array.

For Record inputs, the field names, types
and sizes must match.

The Collector begins with its internal
buffer cleared.  It clears its internal
buffer of collected data each time the XEQ
pin is hit.  It also optionally clears the
buffer at PreRun and Activate.  You also may
force this buffer to be cleared at other
times.  Choose the Clear option from the
object menu, or add a control input for Clear
and programmatically clear the Collector data
before XEQ is hit.  Subsequent hits on the
data input would start the collecting over
again.  The output is not propagated until
XEQ is hit.

If XEQ is hit, and the data input has not
been hit with non-nil data since the last
clear, the Collector will output a nil
signal.

SEE ALSO
Alloc Array, Concatenator, Get Values, Set
Values, and Sliding Collector.
