;+ 
; This function returns a value that, when given as the argument to
; gshift, will shift the primary data container such that it is aligned
; in the current displayed x-axis with the data in the 
; accumulation buffer.  If there is no ongoing accumulation then this
; function returns 0.  The units of the returned value are channels.
; The primary data container must be shifted that many channels in
; order to align in the current x-axis with the data in the
; accumulation buffer.
;
; <p> You can use an alternate data container by setting index.  You
; can use an alternate global accumulation buffer by setting accumnum.
;
; @param accumnum {in}{type=integer}{default=0} accum buffer to use.
; Defaults to the primary buffer, 0.  There are 4 buffers total so
; this value must be between 0 and 3, inclusive.
;
; @keyword index {in}{optional}{type=integer}{default=0} The data
; container that will eventually be shifted.  Defaults to the primary
; data container (0).
;
; @returns shift, in channels, to be used as argument to shift.
; Returns 0.0 on failure.
;
; @examples
; Accumulate several PS scans
; <pre>
; sclear          ; clear the accumulation
; getps, 31       ; get the first scan
; freeze          ; turn off auto-update of the plotter
;
; ; at this point, set the X-axis units using the plotter GUI
;
; accum           ; add the first spectrum to the accumulator
; getps, 32       ; get the next scan, plotter is not auto-updated
; gshift,xshift() ; shift to align the spectrum to the accum'ed spectrum
; accum           ; and add it to the accum buffer
; unfreeze
; ave
; </pre>
;
; @uses <a href="../toolbox/dcxshift.html">dcvshift</a>
;
; @version $Id: xshift.pro,v 1.4 2005/05/24 20:38:35 bgarwood Exp $
;-
function xshift, accumnum, index=index
    compile_opt idl2

    on_error, 2

    if n_elements(accumnum) eq 0 then accumnum = 0

    if (accumnum lt 0 or accumnum gt 3) then begin
        message,'accumnum must be in the range 0 to 3',/info
        return, 0.0
    endif

    if n_elements(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,0.0
    endif
    
    return, dcxshift(!g.accumbuf[accumnum], !g.s[index])
end