ARRINSERT Name
ARRINSERT
Author
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov Purpose
Insert one array into another Calling Sequence
NEWARR = ARRINSERT(INIT, INSERT, [AT=POSITION] )
Description
ARRINSERT inserts the contents of one array (INSERT) into
another (INIT), and returns the new array (NEWARR).
ARRINSERT will handle empty lists, which are represented as
undefined variables. If both input arrays are empty, then the
scalar -1L is returned, and the keyword COUNT is set to 0L.
Inputs
INIT - the initial array, into which INSERT will be inserted. Any
data type, including structures, is allowed. Regardless of
the dimensions of INIT, it is treated as a one-dimensional
array. If OVERWRITE is not set, then INIT itself is
unmodified.
INSERT - the array to be inserted into INIT, which must be of the
same or similar type to INIT. If INSERT is empty, then
INIT is returned unchanged. Regardless of the dimensions
of INSERT, it is treated as a one-dimensional array.
Keywords
AT - a long integer indicating the position of the newly inserted
sub-array. If AT is non-negative, then INSERT will appear
at NEWARR[AT]. If AT is negative, then INSERT will appear
at NEWARR[AT + (N+1)] where N is the number of elements in
INIT, which is to say if AT is negative, it indexes from the
end side of the array rather than the beginning. Thus,
setting AT=-1 will concatenate INIT and INSERT.
Default: 0L (INSERT appears at beginning of INIT)
OVERWRITE - if set, then the initial array INIT will be
overwritten by the new array. Upon exit INIT becomes
undefined.
COUNT - upon return, the number of elements in the resulting
array.
EMPTY1, EMPTY2 - if set, then INIT (for EMPTY1) or INSERT (for
EMPTY2) are assumed to be empty (i.e., to have
zero elements). The actual values passed as INIT
or INSERT are then ignored.
Returns
The new array, which is always one-dimensional. If COUNT is zero,
then the scalar -1L is returned.
Example
X = [1, 2, 3]
Y = [4, 5, 6, 7]
; Insert Y at the beginning of X
result = arrinsert(x, y, at=0)
--> result = [4, 5, 6, 7, 1, 2, 3]
; Insert Y in the middle of X
result = arrinsert(x, y, at=1)
--> result = [1, 4, 5, 6, 7, 2, 3]
; Append Y at the end of X
result = arrinsert(x, y, at=-1)
--> result = [1, 2, 3, 4, 5, 6, 7]
See Also
ARRDELETE, STORE_ARRAY in IDL Astronomy Library
Modification History
Written, CM, 02 Mar 2000
Added OVERWRITE and EMPTY keywords, CM, 04 Mar 2000
Improved internal docs, and AT keyword docs, CM, 28 Sep 2000
Doc clarifications, CM, 29 Sep 2001
Added examples to documentation, CM, 06 Apr 2008