Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


Harris Geospatial / Docs Center / Libraries / Markwardt / ARRINSERT

ARRINSERT

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
  $Id: arrinsert.pro,v 1.4 2008/07/08 20:24:59 craigm Exp $



© 2017 Exelis Visual Information Solutions, Inc. |  Legal
My Account    |    Buy    |    Contact Us