>  Docs Center  >  Libraries  >  Markwardt  >  ARRINSERT






  Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770


  Insert one array into another

Calling Sequence



  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.


  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
  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.


    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
  COUNT - upon return, the number of elements in the resulting
  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.


  The new array, which is always one-dimensional. If COUNT is zero,
  then the scalar -1L is returned.


  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

© 2023 NV5 Geospatial |  Legal
My Account    |    Contact Us