;+
; Shift the data in data container at index by the given number of channels 
; (which may be a floating point number containing fractional
; channels) such that data in channel i before the shift is found in 
; channel i+offset after the shift.  The data's reference channel is
; also shifted so that features should remain stationary when
; displayed except when the x-axis is channels.  Shifted data is
; replaced with zeros unless the /wrap keyword is set in which case
; the data wraps around as necessary during the shift. Data are first
; shifted by the nearest integer number of channels and then the
; result is shifted by the remaining fractional channel if that
; fraction channel is more than ftol.  Currently, fractional shifting is
; done using an FFT windowed using a Welch function to reduce ringing
; as a result of the FFT.  Set ftol to a number >= 1 to turn off all
; fractional shifting.  Eventually other interpolation methods will be
; available.
;
; <p> Use one of xshift, vshift, or fshift to calculate the offset to
; align this data with data in an ongoing accumulation.
;
; <p> Windowing using the Welsh function reduces ringing at the
; expense of the high-order terms in the FFT.  This very slightly
; broadens features.  This can be turned off using the /nowelsh
; keyword.
;
; <p> The data are padded with 0s to the next higher power of two as
; an intermediate step (the final result will have the original size
; of the data).  This is done to reduce ringing due to any
; discontinuities between the two ends of the data.  This can be
; turned off using the /nopad keyword.
;
; @param offset {in}{required}{type=floating point} The number of
; channels to shift the data (positive shifts things towards higher
; channels, negative shifts things towards lower channels).
;
; @keyword index {in}{optional}{type=integer} The data container to
; shift.  All shifting is done in place and so this data container is
; modified by this procedure.
;
; @keyword wrap {in}{optional}{type=boolean} Data shifted off one end
; of the array appears on the other end of the array (it wraps around
; as a result of the shift) when this is set.  Otherwise, as data is
; shifted it is replaced by 0s and data shifted off the end is lost.
; 
; @keyword ftol {in}{optional}{type=floating point}{default=0.01}
; Fractional shifts (the non-integer portion of offset) are only done
; when they are larger than ftol.  Set this value to >= 1.0 to turn
; off all fractional shifts.
;
; @keyword nowelsh {in}{optional}{type=boolean} When set, the shifted
; data is NOT windowed using the Welsh function.
;
; @keyword nopad {in}{optional}{type=boolean} When set, the data is
; NOT padded with 0s to the next higher power of 2 prior to the FFT
; and shift.
;
; @uses <a href="../toolbox/dcshift.html">dcshift</a>
; @uses <a href="../toolbox/data_copy.html">data_copy</a>
; @uses <a href="set_data_container.html">set_data_container</a>
; @uses <a href="../toolbox/data_free.html">data_free</a>
;
; @version $Id: gshift.pro,v 1.4 2005/05/18 19:10:32 bgarwood Exp $
;-
pro gshift, offset, index=index, wrap=wrap, ftol=ftol, nowelsh=nowelsh, nopad=nopad
    compile_opt idl2

    if keyword_set(index) eq 0 then index=0

    if (index lt 0 or index ge n_elements(!g.s)) then begin
        message,string(n_elements(!g.s),format='("index must be >= 0 and < ",i2)'),/info
        return
    endif
    
    data_copy,!g.s[index],shifted
    dcshift,shifted,offset,wrap=wrap,ftol=ftol,nowelsh=nowelsh
    set_data_container,shifted,index=index
    data_free,shifted
end