;-------------------------------------------------------------
;+
; NAME:
;        GTE_INSERTVAR
;
; PURPOSE:
;        Insert a new variable in a dat aarray and the
;        associated variable descriptor
;
; CATEGORY:
;        GTE tools
;
; CALLING SEQUENCE:
;        GTE_INSERTVAR,data,vardesc,newdata,newvardesc,index
;
; INPUTS:
;        DATA -> The pre-existing data array
;
;        VARDESC -> the pre-existing variable descriptor array
;            (an array of structures, see GTE_VARDESC)
;
;        NEWDATA -> The new data vector (!)
;
;        NEWVARDESC -> A single variable descriptor structure
;            containing the information about the new variable
;
;        INDEX -> (optional) Position, where to insert the new
;            variable. Default is to append new variables at the end.
;
; KEYWORD PARAMETERS:
;        none 
;
; OUTPUTS:
;
; SUBROUTINES:
;
; REQUIREMENTS:
;
; NOTES:
;        The type of the new variable is converted to the type
;        of the data set.
;
; EXAMPLE:
;        ; read a binary data set
;        read_bdt0001,'~/tmp/*.bdt',data,vardesc
;        ; create a new variable
;        starttime = data[*,1]-0.5
;        ; create a new variable descriptor
;        newvardesc = gte_vardesc()
;        newvardesc.name = 'STARTTIME'
;        newvardesc.unit = 'secs'
;        ; add new variable at third position
;        gte_insertvar,data,vardesc,starttime,newvardesc,2
;
; MODIFICATION HISTORY:
;        mgs, 24 Aug 1998: VERSION 1.00
;
;-
; Copyright (C) 1998, Martin Schultz, Harvard University
; This software is provided as is without any warranty
; whatsoever. It may be freely used, copied or distributed
; for non-commercial purposes. This copyright notice must be
; kept with any copy of this software. If this software shall
; be used commercially or sold as part of a larger package,
; please contact the author to arrange payment.
; Bugs and comments should be directed to mgs@io.harvard.edu
; with subject "IDL routine gte_insertvar"
;-------------------------------------------------------------


pro gte_insertvar,data,vardesc,newdata,newvardesc,index
 
 
    ; insert a new variable in a data array and the 
    ; the associated variable descriptor
 
    if (n_params() lt 4) then return
 
 
    ; get default: append new variable at end
    if (n_elements(index) eq 0) then index = n_elements(vardesc)
 
    index = (index > 0) < n_elements(vardesc)
 
    ; make sure newdata is vector
    newdata = reform(newdata)

    ; get type information and convert newdata if necessary
    ; *** using new IDL 5.1 keyword)
    dtype = size(data,/type) 

    ; create temporary copy of newdata with correct type
    tmpnew = typecast(newdata,dtype)

    ; append new variable:
    if (index eq n_elements(vardesc)) then begin
       tmp = [ transpose(temporary(data)), transpose(tmpnew) ]
       vardesc = [ vardesc, newvardesc ]
    endif else if (index eq 0) then begin
    ; insert new variable at beginning
       tmp = [ transpose(tmpnew), transpose(temporary(data)) ]
       vardesc = [ newvardesc, vardesc ]
    endif else begin
    ; insert new variable someplace else 
       tmp = [ transpose(temporary(data[*,0:index-1])),  $
               transpose(tmpnew),  $
               transpose(temporary(data[*,index:*])) ]
       vardesc = [ vardesc[0:index-1], newvardesc, vardesc[index:*] ]
    endelse
 
 
    data = transpose(temporary(tmp))
 
    return
 
end