;+ ; 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 ; ; $Id: arrinsert.pro,v 1.4 2008/07/08 20:24:59 craigm Exp $ ; ;- ; Copyright (C) 2000,2001,2008, Craig Markwardt ; This software is provided as is without any warranty whatsoever. ; Permission to use, copy, modify, and distribute modified or ; unmodified copies is granted, provided this copyright and disclaimer ; are included unchanged. ;-